More detailed redirects documentation (#1056)

Added a description, usage and common use cases for each one of the redirects.

src/redirect.rs

@@ -8,7 +8,10 @@ use http::{header, StatusCode};
 pub use self::sealed::AsLocation;
 use crate::reply::{self, Reply};
 
-/// A simple `301` permanent redirect to a different location.
+/// HTTP 301 Moved Permanently
+/// Description: The requested resource has been permanently moved to a new URL.
+/// Usage: It is used when a URL has permanently moved to a new location. Search engines will update their index to the new URL. Browsers and clients will automatically cache this redirect, so subsequent requests for the old URL will automatically go to the new URL without making a request to the old URL.
+/// Common Use Case: Changing domain names, restructuring website URLs.
 ///
 /// # Example
 ///
@@ -28,7 +31,10 @@ pub fn redirect(uri: impl AsLocation) -> impl Reply {
     )
 }
 
-/// A simple `302` found redirect to a different location
+/// HTTP 302 Found (or Temporary Redirect)
+/// Description: The requested resource can be found at a different URL temporarily.
+/// Usage: Historically, this status code was used for temporary redirects. However, its meaning was often misunderstood, and different clients treated it differently. As a result, it is recommended to use 307 (or 303) for temporary redirects instead.
+/// Common Use Case: Rarely used directly due to ambiguity; replaced by 307 or 303.
 ///
 /// # Example
 ///
@@ -44,7 +50,10 @@ pub fn found(uri: impl AsLocation) -> impl Reply {
     reply::with_header(StatusCode::FOUND, header::LOCATION, uri.header_value())
 }
 
-/// A simple `303` redirect to a different location.
+/// HTTP 303 See Other
+/// Description: The response to the request can be found at a different URL, and the client should retrieve it using the GET method.
+/// Usage: It is typically used to redirect the client to another URL using a GET request after processing a POST request. It ensures that the client doesn't repeat the POST request if they refresh the page.
+/// Common Use Case: After form submissions or any non-idempotent request.
 ///
 /// The HTTP method of the request to the new location will always be `GET`.
 ///
@@ -62,7 +71,10 @@ pub fn see_other(uri: impl AsLocation) -> impl Reply {
     reply::with_header(StatusCode::SEE_OTHER, header::LOCATION, uri.header_value())
 }
 
-/// A simple `307` temporary redirect to a different location.
+/// HTTP 307 Temporary Redirect:
+/// Description: The requested resource can be found at a different URL temporarily.
+/// Usage: Similar to 302, but explicitly defined as a temporary redirect. The main difference between 307 and 302 is that 307 preserves the method of the original request when redirecting. If the original request was a POST, the subsequent request to the new URL will also be a POST.
+/// Common Use Case: Temporary redirects that should preserve the original request method.
 ///
 /// This is similar to [`see_other`](fn@see_other) but the HTTP method and the body of the request
 /// to the new location will be the same as the method and body of the current request.
@@ -85,7 +97,10 @@ pub fn temporary(uri: impl AsLocation) -> impl Reply {
     )
 }
 
-/// A simple `308` permanent redirect to a different location.
+/// HTTP 308 Permanent Redirect
+/// Description: The requested resource has been permanently moved to a new URL, and future requests should use the new URL.
+/// Usage: Similar to 301, but like 307, it preserves the original request method when redirecting. It indicates that the redirection is permanent, and browsers and clients will cache this redirect like they do for 301.
+// Common Use Case: Permanently moving resources to a new URL while maintaining the original request method.
 ///
 /// This is similar to [`redirect`](fn@redirect) but the HTTP method of the request to the new
 /// location will be the same as the method of the current request.