From 9e319490798f6a35b24f128fc8c00f4f312d0bdd Mon Sep 17 00:00:00 2001
From: AlphaKeks <85143381+AlphaKeks@users.noreply.github.com>
Date: Mon, 15 Jan 2024 21:49:40 +0100
Subject: [PATCH] Improve documentation of `axum_extra::extract::Query` (#2517)

---
 axum-extra/src/extract/query.rs | 27 +++++++++++++++++++++++++++
 axum/src/extract/query.rs       |  5 +++++
 2 files changed, 32 insertions(+)

diff --git a/axum-extra/src/extract/query.rs b/axum-extra/src/extract/query.rs
index 64ccae5b..3dda1a18 100644
--- a/axum-extra/src/extract/query.rs
+++ b/axum-extra/src/extract/query.rs
@@ -51,6 +51,33 @@ use std::fmt;
 /// example.
 ///
 /// [example]: https://github.com/tokio-rs/axum/blob/main/examples/query-params-with-empty-strings/src/main.rs
+///
+/// While `Option<T>` will handle empty parameters (e.g. `param=`), beware when using this with a
+/// `Vec<T>`. If your list is optional, use `Vec<T>` in combination with `#[serde(default)]`
+/// instead of `Option<Vec<T>>`. `Option<Vec<T>>` will handle 0, 2, or more arguments, but not one
+/// argument.
+///
+/// # Example
+///
+/// ```rust,no_run
+/// use axum::{routing::get, Router};
+/// use axum_extra::extract::Query;
+/// use serde::Deserialize;
+///
+/// #[derive(Deserialize)]
+/// struct Params {
+///     #[serde(default)]
+///     items: Vec<usize>,
+/// }
+///
+/// // This will parse 0 occurrences of `items` as an empty `Vec`.
+/// async fn process_items(Query(params): Query<Params>) {
+///     // ...
+/// }
+///
+/// let app = Router::new().route("/process_items", get(process_items));
+/// # let _: Router = app;
+/// ```
 #[cfg_attr(docsrs, doc(cfg(feature = "query")))]
 #[derive(Debug, Clone, Copy, Default)]
 pub struct Query<T>(pub T);
diff --git a/axum/src/extract/query.rs b/axum/src/extract/query.rs
index a0c0f77c..a331b68c 100644
--- a/axum/src/extract/query.rs
+++ b/axum/src/extract/query.rs
@@ -42,6 +42,11 @@ use serde::de::DeserializeOwned;
 /// example.
 ///
 /// [example]: https://github.com/tokio-rs/axum/blob/main/examples/query-params-with-empty-strings/src/main.rs
+///
+/// For handling multiple values for the same query parameter, in a `?foo=1&foo=2&foo=3`
+/// fashion, use [`axum_extra::extract::Query`] instead.
+///
+/// [`axum_extra::extract::Query`]: https://docs.rs/axum-extra/latest/axum_extra/extract/struct.Query.html
 #[cfg_attr(docsrs, doc(cfg(feature = "query")))]
 #[derive(Debug, Clone, Copy, Default)]
 pub struct Query<T>(pub T);