From 76268ae52bc88859ccb55a785e710d460d47c7d5 Mon Sep 17 00:00:00 2001 From: reivilibre Date: Thu, 14 Aug 2025 10:10:52 +0100 Subject: [PATCH] Document type parameter `T` on `Handler` (#3435) Signed-off-by: Olivier 'reivilibre --- axum/src/handler/mod.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/axum/src/handler/mod.rs b/axum/src/handler/mod.rs index c7a02425..e99be5f8 100644 --- a/axum/src/handler/mod.rs +++ b/axum/src/handler/mod.rs @@ -125,6 +125,23 @@ pub use self::service::HandlerService; /// ))); /// # let _: Router = app; /// ``` +/// +/// # About type parameter `T` +/// +/// **Generally you shouldn't need to worry about `T`**; when calling methods such as +/// [`post`](crate::routing::method_routing::post) it will be automatically inferred and this is +/// the intended way for this parameter to be provided in application code. +/// +/// If you are implementing your own methods that accept implementations of `Handler` as +/// arguments, then the following may be useful: +/// +/// The type parameter `T` is a workaround for trait coherence rules, allowing us to +/// write blanket implementations of `Handler` over many types of handler functions +/// with different numbers of arguments, without the compiler forbidding us from doing +/// so because one type `F` can in theory implement both `Fn(A) -> X` and `Fn(A, B) -> Y`. +/// `T` is a placeholder taking on a representation of the parameters of the handler function, +/// as well as other similar 'coherence rule workaround' discriminators, +/// allowing us to select one function signature to use as a `Handler`. #[diagnostic::on_unimplemented( note = "Consider using `#[axum::debug_handler]` to improve the error message" )]