#[pyo3::pymodule] triggers missing documentation for a module lint

[konstin]

Bug Description

I'm using roughly this code:

#![warn(missing_docs)]

#[cfg(feature = "pyo3")]
pub use version::PyVersion;

mod version;

#[cfg(feature = "pyo3")]
#[pyo3::pymodule]
#[pyo3(name = "_pep440_rs")]
/// Python bindings shipped as `pep440_rs`
pub fn python_module(module: &pyo3::Bound<'_, pyo3::types::PyModule>) -> pyo3::PyResult<()> {
    module.add_class::<PyVersion>()?;
    Ok(())
}

This causes a lint error:

warning: missing documentation for a module
  --> src/lib.rs:51:1
   |
51 | #[pyo3::pymodule]
   | ^^^^^^^^^^^^^^^^^
   |
note: the lint level is defined here
  --> src/lib.rs:35:9
   |
35 | #![warn(missing_docs)]
   |         ^^^^^^^^^^^^
   = note: this warning originates in the attribute macro `pyo3::pymodule` (in Nightly builds, run with -Z macro-backtrace for more info)

This lint error is confusing, because i didn't define a rust module (i defined a function) and that function has a docstring.

Steps to Reproduce

git clone https://github.com/konstin/pep440-rs
cd pep440-rs
git checkout fbabd0e8fdbabb6b310ad2e5b119d9a031b34bd4
cargo clippy --all-features

Backtrace

n/a

Your operating system and version

ubuntu 22.04

Your Python version (python --version)

Python 3.12.1

Your Rust version (rustc --version)

rustc 1.77.1 (7cf61ebde 2024-03-27)

Your PyO3 version

0.21.1

How did you install python? Did you use a virtualenv?

pyenv, yes.

Additional Info

No response

[Icxolu]

I think the problem here is, that #[pymodule] creates a Rust module (at the same visibility as the function) during macro expansion. As a workaround you could just make python_module private or pub(crate), which will not trigger the lint. The real solution is probably to emit #[doc(hidden)] on that module during expansion.

[konstin]

Both the original function and the generated module currently does currently show up in rustdoc, but the latter without docs

[Icxolu]

Yep, given that all items inside of that module already have #[doc(hidden)] attached, I think it's reasonable to also hide the module itself. I opened #4067 to fix that.