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)
     }