Add #[must_use] to types and methods (#3395)

Co-authored-by: Theodore Bjernhed <[email protected]>

axum-extra/src/extract/cookie/mod.rs

@@ -84,6 +84,7 @@ pub use cookie::Key;
 ///     .route("/me", get(me));
 /// # let app: Router = app;
 /// ```
+#[must_use = "`CookieJar` should be returned as part of a `Response`, otherwise it does nothing."]
 #[derive(Debug, Default, Clone)]
 pub struct CookieJar {
     jar: cookie::CookieJar,
@@ -153,6 +154,7 @@ impl CookieJar {
     ///         .map(|cookie| cookie.value().to_owned());
     /// }
     /// ```
+    #[must_use]
     pub fn get(&self, name: &str) -> Option<&Cookie<'static>> {
         self.jar.get(name)
     }
@@ -169,7 +171,6 @@ impl CookieJar {
     ///     jar.remove(Cookie::from("foo"))
     /// }
     /// ```
-    #[must_use]
     pub fn remove<C: Into<Cookie<'static>>>(mut self, cookie: C) -> Self {
         self.jar.remove(cookie);
         self
@@ -189,7 +190,6 @@ impl CookieJar {
     ///     jar.add(Cookie::new("foo", "bar"))
     /// }
     /// ```
-    #[must_use]
     #[allow(clippy::should_implement_trait)]
     pub fn add<C: Into<Cookie<'static>>>(mut self, cookie: C) -> Self {
         self.jar.add(cookie);

axum-extra/src/extract/cookie/private.rs

@@ -104,6 +104,7 @@ use std::{convert::Infallible, fmt, marker::PhantomData};
 ///     }
 /// }
 /// ```
+#[must_use = "`PrivateCookieJar` should be returned as part of a `Response`, otherwise it does nothing."]
 pub struct PrivateCookieJar<K = Key> {
     jar: cookie::CookieJar,
     key: Key,
@@ -201,6 +202,7 @@ impl<K> PrivateCookieJar<K> {
     ///         .map(|cookie| cookie.value().to_owned());
     /// }
     /// ```
+    #[must_use]
     pub fn get(&self, name: &str) -> Option<Cookie<'static>> {
         self.private_jar().get(name)
     }
@@ -217,7 +219,6 @@ impl<K> PrivateCookieJar<K> {
     ///     jar.remove(Cookie::from("foo"))
     /// }
     /// ```
-    #[must_use]
     pub fn remove<C: Into<Cookie<'static>>>(mut self, cookie: C) -> Self {
         self.private_jar_mut().remove(cookie);
         self
@@ -237,7 +238,6 @@ impl<K> PrivateCookieJar<K> {
     ///     jar.add(Cookie::new("foo", "bar"))
     /// }
     /// ```
-    #[must_use]
     #[allow(clippy::should_implement_trait)]
     pub fn add<C: Into<Cookie<'static>>>(mut self, cookie: C) -> Self {
         self.private_jar_mut().add(cookie);
@@ -246,6 +246,7 @@ impl<K> PrivateCookieJar<K> {
 
     /// Authenticates and decrypts `cookie`, returning the plaintext version if decryption succeeds
     /// or `None` otherwise.
+    #[must_use]
     pub fn decrypt(&self, cookie: Cookie<'static>) -> Option<Cookie<'static>> {
         self.private_jar().decrypt(cookie)
     }
@@ -284,6 +285,7 @@ impl<K> IntoResponse for PrivateCookieJar<K> {
     }
 }
 
+#[must_use = "iterators are lazy and do nothing unless consumed"]
 struct PrivateCookieJarIter<'a, K> {
     jar: &'a PrivateCookieJar<K>,
     iter: cookie::Iter<'a>,

axum-extra/src/extract/cookie/signed.rs

@@ -121,6 +121,7 @@ use std::{convert::Infallible, fmt, marker::PhantomData};
 ///     }
 /// }
 /// ```
+#[must_use = "`SignedCookieJar` should be returned as part of a `Response`, otherwise it does nothing."]
 pub struct SignedCookieJar<K = Key> {
     jar: cookie::CookieJar,
     key: Key,
@@ -219,6 +220,7 @@ impl<K> SignedCookieJar<K> {
     ///         .map(|cookie| cookie.value().to_owned());
     /// }
     /// ```
+    #[must_use]
     pub fn get(&self, name: &str) -> Option<Cookie<'static>> {
         self.signed_jar().get(name)
     }
@@ -235,7 +237,6 @@ impl<K> SignedCookieJar<K> {
     ///     jar.remove(Cookie::from("foo"))
     /// }
     /// ```
-    #[must_use]
     pub fn remove<C: Into<Cookie<'static>>>(mut self, cookie: C) -> Self {
         self.signed_jar_mut().remove(cookie);
         self
@@ -255,7 +256,6 @@ impl<K> SignedCookieJar<K> {
     ///     jar.add(Cookie::new("foo", "bar"))
     /// }
     /// ```
-    #[must_use]
     #[allow(clippy::should_implement_trait)]
     pub fn add<C: Into<Cookie<'static>>>(mut self, cookie: C) -> Self {
         self.signed_jar_mut().add(cookie);
@@ -264,6 +264,7 @@ impl<K> SignedCookieJar<K> {
 
     /// Verifies the authenticity and integrity of `cookie`, returning the plaintext version if
     /// verification succeeds or `None` otherwise.
+    #[must_use]
     pub fn verify(&self, cookie: Cookie<'static>) -> Option<Cookie<'static>> {
         self.signed_jar().verify(cookie)
     }
@@ -302,6 +303,7 @@ impl<K> IntoResponse for SignedCookieJar<K> {
     }
 }
 
+#[must_use = "iterators are lazy and do nothing unless consumed"]
 struct SignedCookieJarIter<'a, K> {
     jar: &'a SignedCookieJar<K>,
     iter: cookie::Iter<'a>,

axum-extra/src/extract/multipart.rs

@@ -150,6 +150,7 @@ impl Field {
     /// The field name found in the
     /// [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)
     /// header.
+    #[must_use]
     pub fn name(&self) -> Option<&str> {
         self.inner.name()
     }
@@ -157,16 +158,19 @@ impl Field {
     /// The file name found in the
     /// [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)
     /// header.
+    #[must_use]
     pub fn file_name(&self) -> Option<&str> {
         self.inner.file_name()
     }
 
     /// Get the [content type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) of the field.
+    #[must_use]
     pub fn content_type(&self) -> Option<&str> {
         self.inner.content_type().map(|m| m.as_ref())
     }
 
     /// Get a map of headers as [`HeaderMap`].
+    #[must_use]
     pub fn headers(&self) -> &HeaderMap {
         self.inner.headers()
     }
@@ -253,6 +257,7 @@ impl MultipartError {
     }
 
     /// Get the status code used for this rejection.
+    #[must_use]
     pub fn status(&self) -> http::StatusCode {
         status_code_from_multer_error(&self.source)
     }

axum-extra/src/response/file_stream.rs

@@ -44,6 +44,7 @@ use tokio_util::io::ReaderStream;
 /// let app = Router::new().route("/file-stream", get(file_stream));
 /// # let _: Router = app;
 /// ```
+#[must_use]
 #[derive(Debug)]
 pub struct FileStream<S> {
     /// stream.

axum-extra/src/response/multiple.rs

@@ -8,6 +8,7 @@ use mime::Mime;
 /// Create multipart forms to be used in API responses.
 ///
 /// This struct implements [`IntoResponse`], and so it can be returned from a handler.
+#[must_use]
 #[derive(Debug)]
 pub struct MultipartForm {
     parts: Vec<Part>,
@@ -103,6 +104,7 @@ impl Part {
     /// let parts: Vec<Part> = vec![Part::text("foo".to_string(), "abc")];
     /// let form = MultipartForm::from_iter(parts);
     /// ```
+    #[must_use]
     pub fn text(name: String, contents: &str) -> Self {
         Self {
             name,
@@ -127,6 +129,7 @@ impl Part {
     /// let parts: Vec<Part> = vec![Part::file("foo", "foo.txt", vec![0x68, 0x68, 0x20, 0x6d, 0x6f, 0x6d])];
     /// let form = MultipartForm::from_iter(parts);
     /// ```
+    #[must_use]
     pub fn file(field_name: &str, file_name: &str, contents: Vec<u8>) -> Self {
         Self {
             name: field_name.to_owned(),

axum-extra/src/routing/mod.rs

@@ -28,6 +28,7 @@ pub use self::typed::{SecondElementIs, TypedPath};
 // Validates a path at compile time, used with the vpath macro.
 #[rustversion::since(1.80)]
 #[doc(hidden)]
+#[must_use]
 pub const fn __private_validate_static_path(path: &'static str) -> &'static str {
     if path.is_empty() {
         panic!("Paths must start with a `/`. Use \"/\" for root routes")
@@ -76,6 +77,7 @@ macro_rules! vpath {
 }
 
 /// Extension trait that adds additional methods to [`Router`].
+#[allow(clippy::return_self_not_must_use)]
 pub trait RouterExt<S>: sealed::Sealed {
     /// Add a typed `GET` route to the router.
     ///

axum-extra/src/typed_header.rs

@@ -137,11 +137,13 @@ pub struct TypedHeaderRejection {
 
 impl TypedHeaderRejection {
     /// Name of the header that caused the rejection
+    #[must_use]
     pub fn name(&self) -> &http::header::HeaderName {
         self.name
     }
 
     /// Reason why the header extraction has failed
+    #[must_use]
     pub fn reason(&self) -> &TypedHeaderRejectionReason {
         &self.reason
     }