有没有办法从文档中隐藏宏模式?
Is there a way to hide a macro pattern from docs?
从 Rust 1.6.0 开始,生成的文档隐藏了每个宏模式的实现:
有没有办法从 Cargo 生成的文档中隐藏某些模式?
macro_rules! mc {
// hide this entire pattern
(@impl, $arg:expr) => { 42 + $arg };
// but not this one
($arg:expr) => { mc!(@impl, $arg) };
}
我想这是最佳解决方案:
/// Not meant to be called directly
#[doc(hidden)]
#[macro_export]
macro_rules! hidden {
( $hidden_rule1:expr ) => { ... };
( $hidden_rule2:expr ) => { ... };
...
}
#[macro_export]
macro_rules! public {
( $public:expr ) => ( hidden!($public) );
}
这使用了一个单独的 hidden
宏(可能需要 public),但它不是文档的一部分。所有应该隐藏的规则都将被隐藏,public 规则将在作为文档一部分的 public
宏中可见。
一个选项是有一个只有 public 臂的虚拟宏,并使用属性来选择 rustdoc 看到的:
/// Do a thing
///
/// ```
/// # extern crate my_crate;
/// # use my_crate::mc;
/// assert_eq!(mc!(58), 100);
/// ```
#[cfg(doc)]
#[macro_export]
macro_rules! mc {
($arg:expr) => { ... };
}
#[cfg(not(doc))]
#[macro_export]
macro_rules! mc {
(@impl, $arg:expr) => { 42 + $arg };
($arg:expr) => { mc!(@impl, $arg) };
}
注意:这仅在您不在内部使用宏时才有效。
从 Rust 1.6.0 开始,生成的文档隐藏了每个宏模式的实现:
有没有办法从 Cargo 生成的文档中隐藏某些模式?
macro_rules! mc {
// hide this entire pattern
(@impl, $arg:expr) => { 42 + $arg };
// but not this one
($arg:expr) => { mc!(@impl, $arg) };
}
我想这是最佳解决方案:
/// Not meant to be called directly
#[doc(hidden)]
#[macro_export]
macro_rules! hidden {
( $hidden_rule1:expr ) => { ... };
( $hidden_rule2:expr ) => { ... };
...
}
#[macro_export]
macro_rules! public {
( $public:expr ) => ( hidden!($public) );
}
这使用了一个单独的 hidden
宏(可能需要 public),但它不是文档的一部分。所有应该隐藏的规则都将被隐藏,public 规则将在作为文档一部分的 public
宏中可见。
一个选项是有一个只有 public 臂的虚拟宏,并使用属性来选择 rustdoc 看到的:
/// Do a thing
///
/// ```
/// # extern crate my_crate;
/// # use my_crate::mc;
/// assert_eq!(mc!(58), 100);
/// ```
#[cfg(doc)]
#[macro_export]
macro_rules! mc {
($arg:expr) => { ... };
}
#[cfg(not(doc))]
#[macro_export]
macro_rules! mc {
(@impl, $arg:expr) => { 42 + $arg };
($arg:expr) => { mc!(@impl, $arg) };
}
注意:这仅在您不在内部使用宏时才有效。