Hide Internal Rules in macro_rules!
Docs
When generating docs for macro_rules!
macros, rustdoc
will include every
rule, including internal rules that are only supposed to be called from within
your macro. The clean_docs
attribute will hide your internal rules from
rustdoc
.
Example:
would be documented as
How does it work?
The macro above is transformed into
The last, non-macro_export
macro is there becuase Rust doesn't allow
macro-expanded macro to be invoked by absolute path (i.e. $crate::__mac
).
The solution is to shadow the macro_export
ed macro with a local version
that doesn't use absolute paths.
By default this transformation only happens when rustdoc
is building the
documentation for your macro, so clean_docs
shouldn't affect your normal
compilation times (see always
).
Arguments
You can use these optional arguments to configure clean_macro
.
impl
A string representing the "flag" at the begining of an internal rule. Defaults to "@"
.
internal
A string representing the identifier to use for the internal version of your macro.
By default clean_docs
prepends __
(two underscores) to the main macro's identifier.
always
A boolean that tells clean_docs
whether it should transform the macro
even when not building documentation. This is mainly used for testing
purposes. Defaults to false
.