Document debugging handler type errors with "axum-debug" (#372)

* Document debugging handler type errors with "axum-debug"

* Apply suggestions from code review

Co-authored-by: Jonas Platte <[email protected]>

Co-authored-by: Jonas Platte <[email protected]>

src/lib.rs

@@ -5,6 +5,7 @@
 //! - [High level features](#high-level-features)
 //! - [Compatibility](#compatibility)
 //! - [Handlers](#handlers)
+//!     - [Debugging handler type errors](#debugging-handler-type-errors)
 //! - [Routing](#routing)
 //!     - [Precedence](#precedence)
 //!     - [Matching multiple methods](#matching-multiple-methods)
@@ -106,6 +107,41 @@
 //! }
 //! ```
 //!
+//! ## Debugging handler type errors
+//!
+//! For a function to used as a handler it must implement the [`Handler`] trait.
+//! axum provides blanket implementations for functions that:
+//!
+//! - Are `async fn`s.
+//! - Take no more than 16 arguments that all implement [`FromRequest`].
+//! - Returns something that implements [`IntoResponse`].
+//! - If a closure is used it must implement `Clone + Send + Sync` and be
+//! `'static`.
+//! - Returns a future that is `Send`. The most common way to accidentally make a
+//! future `!Send` is to hold a `!Send` type across an await.
+//!
+//! Unfortunately Rust gives poor error messages if you try to use a function
+//! that doesn't quite match what's required by [`Handler`].
+//!
+//! You might get an error like this:
+//!
+//! ```not_rust
+//! error[E0277]: the trait bound `fn(bool) -> impl Future {handler}: Handler<_, _>` is not satisfied
+//!    --> src/main.rs:13:44
+//!     |
+//! 13  |     let app = Router::new().route("/", get(handler));
+//!     |                                            ^^^^^^^ the trait `Handler<_, _>` is not implemented for `fn(bool) -> impl Future {handler}`
+//!     |
+//!    ::: axum/src/handler/mod.rs:116:8
+//!     |
+//! 116 |     H: Handler<B, T>,
+//!     |        ------------- required by this bound in `axum::handler::get`
+//! ```
+//!
+//! This error doesn't tell you _why_ your function doesn't implement
+//! [`Handler`]. It's possible to improve the error with the [`debug_handler`]
+//! proc-macro from the [axum-debug] crate.
+//!
 //! # Routing
 //!
 //! Routing between handlers looks like this:
@@ -1150,6 +1186,9 @@
 //! [`HeaderMap`]: http::header::HeaderMap
 //! [`Request`]: http::Request
 //! [customize-extractor-error]: https://github.com/tokio-rs/axum/blob/main/examples/customize-extractor-error/src/main.rs
+//! [axum-debug]: https://docs.rs/axum-debug
+//! [`debug_handler`]: https://docs.rs/axum-debug/latest/axum_debug/attr.debug_handler.html
+//! [`Handler`]: crate::handler::Handler
 
 #![warn(
     clippy::all,