Incompatibility between axum_macros::debug_handler and Clippy

[decryphe]

Summary

We try to use as many lints as possible on our project, so that issues are caught as early as possible. That's why we use Clippy for many extra lints that are useful.

There is one lint that fails when using #[axum_macros::debug_handler] on any axum handler: clippy::missing-docs-in-private-items

Removing the #[axum_macros::debug_handler] attribute makes the error go away.

Presumably, axum_macros generates some functions that are not documented during generation and as such get caught by Clippy. It's not possible to fix the lint rule requirements as a user of the lint or the macro. I'm not familiar with how Clippy normally deals with generated code that is never seen or accessed directly by a developer.

Lint Name

clippy::missing-docs-in-private-items

Reproducer

Cargo.toml:

[package]
name = "axum-clippy"
version = "0.0.0"
edition = "2021"
publish = false

[dependencies]
axum = { version="0.5.1" }
axum-macros = "0.2.0"
serde = { version = "1.0.136", features = ["derive"] }
serde_json = "1.0.79"
tokio = { version = "1.16.1", features = ["full"] }
tokio-stream = { version = "0.1.8" }

src/main.rs:

//! Sample application showing axum/clippy incompatibility

use axum::{routing::get, Router};

#[tokio::main]
async fn main() {
    let app = Router::new().route("/", get(root));

    // run our app with hyper
    // `axum::Server` is a re-export of `hyper::Server`
    let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 3000));
    axum::Server::bind(&addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

/// GET Response Body for `/`
#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
pub struct Sample {
    /// Put whatever in here.
    pub something: String,
}

/// Handler for GET `/`
#[axum_macros::debug_handler]
pub async fn root() -> axum::Json<Sample> {
    let response = Sample {
        something: "Hello World".into(),
    };

    axum::Json(response)
}

How to enable the additional lints:
RUSTFLAGS="-D warnings -D missing_docs -D clippy::doc_markdown -D clippy::missing_docs_in_private_items" cargo clippy

The error output from running cargo clippy:

error: missing documentation for a function
  --> src/main.rs:27:24
   |
27 | pub async fn root() -> axum::Json<Sample> {
   |                        ^^^^
   |
   = note: requested on the command line with `-D clippy::missing-docs-in-private-items`
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_docs_in_private_items

error: missing documentation for a function
  --> src/main.rs:25:1
   |
25 | /// Handler for GET `/`
   | ^^^^^^^^^^^^^^^^^^^^^^^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_docs_in_private_items

error: could not compile `axum-clippy` due to 2 previous errors

Version

rustc 1.60.0 (7737e0b5c 2022-04-04)
binary: rustc
commit-hash: 7737e0b5c4103216d6fd8cf941b7ab9bdbaace7c
commit-date: 2022-04-04
host: x86_64-unknown-linux-gnu
release: 1.60.0
LLVM version: 14.0.0

Additional Labels

No response