Version 0.2.8 (#374)

* 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]>

* Version 0.2.8

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

[#372]: https://github.com/tokio-rs/axum/pull/372

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

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - None
 
+# 0.2.8 (07. October, 2021)
+
+- Document debugging handler type errors with "axum-debug" ([#372])
+
+[#372]: https://github.com/tokio-rs/axum/pull/372
+
 # 0.2.7 (06. October, 2021)
 
 - Bump minimum version of async-trait ([#370])

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "axum"
-version = "0.2.7"
+version = "0.2.8"
 authors = ["David Pedersen <[email protected]>"]
 categories = ["asynchronous", "network-programming", "web-programming"]
 description = "Web framework that focuses on ergonomics and modularity"

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:
@@ -1147,6 +1183,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,