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
.
#[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! messy {
(@impl $e:expr) => { ... };
($e:expr) => { ... };
}
macro_rules! clean {
($e:expr) => { ... };
}
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.
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
).
You can use these optional arguments to configure clean_macro
.
#[clean_docs(impl = "#internal", internal = "__internal_mac", always = true)]
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)
};
}
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)
};
}
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
.
#[clean_docs(always = true)]
#[macro_export]
macro_rules! mac {
(@impl $e:expr) => {
format!("{}", $e)
};
($e:expr) => {
mac!(@impl $e)
};
}