From 9257de40fd18cf5a4319396e8fcfe9234cb8345e Mon Sep 17 00:00:00 2001
From: David Hewitt <1939362+davidhewitt@users.noreply.github.com>
Date: Tue, 27 Sep 2022 07:55:21 +0100
Subject: [PATCH] docs: note that `#[pymodule]` will create hidden module, like
 `#[pyfunction]`

---
 pyo3-macros/src/lib.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/pyo3-macros/src/lib.rs b/pyo3-macros/src/lib.rs
index dc6ced6a..873fe306 100644
--- a/pyo3-macros/src/lib.rs
+++ b/pyo3-macros/src/lib.rs
@@ -30,6 +30,11 @@ use syn::{parse::Nothing, parse_macro_input};
 ///
 /// For more on creating Python modules see the [module section of the guide][1].
 ///
+/// Due to technical limitations on how `#[pymodule]` is implemented, a function marked
+/// `#[pymodule]` cannot have a module with the same name in the same scope. (The
+/// `#[pymodule]` implementation generates a hidden module with the same name containing
+/// metadata about the module, which is used by `wrap_pymodule!`).
+///
 /// [1]: https://pyo3.rs/latest/module.html
 #[proc_macro_attribute]
 pub fn pymodule(args: TokenStream, input: TokenStream) -> TokenStream {