Crate clean_macro_docs[−][src]
Hide internal rules when documenting macro_rules!
macros.
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:
#[macro_export] macro_rules! messy { (@impl $e:expr) => { format!("{}", $e) }; ($e:expr) => { messy!(@impl $e) }; } #[clean_docs] #[macro_export] macro_rules! clean { (@impl $e:expr) => { format!("{}", $e) }; ($e:expr) => { clean!(@impl $e) }; }
would be documented as
macro_rules! mac { ($e:expr) => { ... }; }
How does it work?
The clean!
macro above is transformed into
#[macro_export] macro_rules! clean { ($e:expr) => { $crate::__clean!(@impl $e) }; } #[macro_export] macro_rules! __clean { (@impl $e:expr) => { format!("{}", $e) }; } macro_rules! clean { (@impl $e:expr) => { format!("{}", $e) }; ($e:expr) => { clean!(@impl $e) }; }
The last, non-macro_export
ed macro is there becuase Rust doesn't allow
macro-expanded macros to be invoked by absolute path (i.e. $crate::__clean
).
The solution is to shadow the macro_export
ed macro with a local version
that doesn't use absolute paths.
Arguments
You can use these optional arguments to configure clean_macro
.
#[clean_docs(impl = "#internal", internal = "__internal_mac")]
impl
A string representing the "flag" at the begining of an internal rule. Defaults to "@"
.
#[clean_docs(impl = "#internal")] #[macro_export] macro_rules! mac { (#internal $e:expr) => { format!("{}", $e) }; ($e:expr) => { mac!(#internal $e) }; }
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.
#[clean_docs(internal = "__internal_mac")] #[macro_export] macro_rules! mac { (@impl $e:expr) => { format!("{}", $e) }; ($e:expr) => { mac!(@impl $e) }; }
Attribute Macros
clean_docs |