[rustdoc] Private macros are not documented with --document-private-items

[TyPR124]

Rustdoc has --document-private-items and --document-hidden-items. It would be nice to have an option to document non-exported macros, which is currently not possible as far as I can tell.

[jonas-schievink]

I would expect --document-private-items to also document macros, so this seems like a bug

[jyn514]

This is because rustdoc gets macros from Crate.exported_macros, which doesn't have the private macros in the first place. Intra-doc links don't have this problem because they look at Resolver::all_macros. Maybe the rest of rustdoc could use that too?

[camelid]

Marking as P-medium since this behavior is pretty confusing.

[camelid]

Going to try working on this. Hopefully I won't regret it ;)

[jyn514]

Copying from #79396 (comment):

The rustdoc-based solution is a workaround and technical debt.

For modularized macros (macro and pub macro_rules, if they get merged) their source parent module (the module into which they are placed in source code) and their name-resolution parent module (parent::my_macro) coincide , so preserving these macro items in HIR would be the most natural way to give these items to rustdoc (and perhaps save-analysis as well), in both regular and document-private-items rustdoc mode.
Rustdoc then wouldn't require any special treatment of these macros compared to other items.

macro_rules without #[macro_export] are only documented in document-private-items mode, and correct location for documenting them doesn't really exist, so documenting them in the module in which they are written in source code would be good enough.
That means preserving these macros in HIR and treating exactly like the macro items mentioned above would be the simplest solution.

#[macro_export] macro_rules are the most annoying case.
They may be defined in some module in source code, but they still need to be documented documented in the crate root by rustdoc (and also encoded as placed into the crate root in metadata).
I'm not sure what is the cleanest way to address them, perhaps moving them all into the root module during lowering to HIR would work?

[jyn514]

Fixing this properly would also allow removing the hack in #77862.

[inquisitivecrystal]

This should get fixed as part of #87406.