From 536b9b966e2142126cef44d08a882e09af935c33 Mon Sep 17 00:00:00 2001
From: Alexander Jackson <alexanderjackson@protonmail.com>
Date: Wed, 27 Jan 2021 10:46:00 +0000
Subject: [PATCH] Improve `impl ResponseError` documentation

Improve the detail of documentation for different implementations of
`ResponseError` on other errors. Most of these return the basic
`StatusCode::INTERNAL_SERVER_ERROR` but some depend on the contents of
the error, so these are explained as well.

Fixes #1886.
---
 actix-http/src/error.rs | 37 ++++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 15 deletions(-)

diff --git a/actix-http/src/error.rs b/actix-http/src/error.rs
index 9ff154240..ab3f9c6bb 100644
--- a/actix-http/src/error.rs
+++ b/actix-http/src/error.rs
@@ -147,7 +147,10 @@ impl From<ResponseBuilder> for Error {
     }
 }
 
-/// Return `GATEWAY_TIMEOUT` for `TimeoutError`
+/// Inspects the underlying enum and returns an appropriate status code.
+///
+/// If the variant is [`TimeoutError::Service`], the error code of the service is returned.
+/// Otherwise, [`StatusCode::GATEWAY_TIMEOUT`] is returned.
 impl<E: ResponseError> ResponseError for TimeoutError<E> {
     fn status_code(&self) -> StatusCode {
         match self {
@@ -161,41 +164,44 @@ impl<E: ResponseError> ResponseError for TimeoutError<E> {
 #[display(fmt = "UnknownError")]
 struct UnitError;
 
-/// `InternalServerError` for `UnitError`
+/// Returns [`StatusCode::INTERNAL_SERVER_ERROR`] for [`UnitError`].
 impl ResponseError for UnitError {}
 
-/// `InternalServerError` for `JsonError`
+/// Returns [`StatusCode::INTERNAL_SERVER_ERROR`] for [`JsonError`].
 impl ResponseError for JsonError {}
 
-/// `InternalServerError` for `FormError`
+/// Returns [`StatusCode::INTERNAL_SERVER_ERROR`] for [`FormError`].
 impl ResponseError for FormError {}
 
 #[cfg(feature = "openssl")]
-/// `InternalServerError` for `openssl::ssl::Error`
+/// Returns [`StatusCode::INTERNAL_SERVER_ERROR`] for [`actix_tls::accept::openssl::SslError`].
 impl ResponseError for actix_tls::accept::openssl::SslError {}
 
-/// Return `BAD_REQUEST` for `de::value::Error`
+/// Returns [`StatusCode::BAD_REQUEST`] for [`DeError`].
 impl ResponseError for DeError {
     fn status_code(&self) -> StatusCode {
         StatusCode::BAD_REQUEST
     }
 }
 
-/// `InternalServerError` for `Canceled`
+/// Returns [`StatusCode::INTERNAL_SERVER_ERROR`] for [`Canceled`].
 impl ResponseError for Canceled {}
 
-/// Return `BAD_REQUEST` for `Utf8Error`
+/// Returns [`StatusCode::BAD_REQUEST`] for [`Utf8Error`].
 impl ResponseError for Utf8Error {
     fn status_code(&self) -> StatusCode {
         StatusCode::BAD_REQUEST
     }
 }
 
-/// Return `InternalServerError` for `HttpError`,
-/// Response generation can return `HttpError`, so it is internal error
+/// Returns [`StatusCode::INTERNAL_SERVER_ERROR`] for [`HttpError`].
 impl ResponseError for HttpError {}
 
-/// Return `InternalServerError` for `io::Error`
+/// Inspects the underlying [`io::ErrorKind`] and returns an appropriate status code.
+///
+/// If the error is [`io::ErrorKind::NotFound`], [`StatusCode::NOT_FOUND`] is returned. If the
+/// error is [`io::ErrorKind::PermissionDenied`], [`StatusCode::FORBIDDEN`] is returned. Otherwise,
+/// [`StatusCode::INTERNAL_SERVER_ERROR`] is returned.
 impl ResponseError for io::Error {
     fn status_code(&self) -> StatusCode {
         match self.kind() {
@@ -206,7 +212,7 @@ impl ResponseError for io::Error {
     }
 }
 
-/// `BadRequest` for `InvalidHeaderValue`
+/// Returns [`StatusCode::BAD_REQUEST`] for [`header::InvalidHeaderValue`].
 impl ResponseError for header::InvalidHeaderValue {
     fn status_code(&self) -> StatusCode {
         StatusCode::BAD_REQUEST
@@ -969,9 +975,10 @@ where
     InternalError::new(err, StatusCode::NETWORK_AUTHENTICATION_REQUIRED).into()
 }
 
-#[cfg(feature = "actors")]
-/// `InternalServerError` for `actix::MailboxError`
-/// This is supported on feature=`actors` only
+#[cfg(feature = "actors")pp]
+/// Returns [`StatusCode::INTERNAL_SERVER_ERROR`] for [`actix::MailboxError`].
+///
+/// This is only supported when the feature `actors` is enabled.
 impl ResponseError for actix::MailboxError {}
 
 #[cfg(test)]