Not sure if this should be RFC or issue… But this affects how we expose methods for documentation so I’m inclined for RFC.
Motivations
Document platform-specific APIs
Example:
/// Open the web page in Internet Explorer.
#[cfg(target_os="win32")]
pub fn open_in_internet_explorer(url: &str) { ... }
/// Open the web page in Safari
#[cfg(any(target_os="macos", target_os="win32"))]
pub fn open_in_safari(url: &str) { ... }
In the current architecture, some of the above API will be missing depending on the machine calling rustdoc/cargo doc. However, we could ensure both will appear in the documentation if the tool provide a specific config:
/// Open the web page in Internet Explorer.
#[cfg(any(rustdoc, target_os="win32"))]
pub fn open_in_internet_explorer(url: &str) { ... }
/// Open the web page in Safari
#[cfg(any(rustdoc, target_os="macos", target_os="win32"))]
pub fn open_in_safari(url: &str) { ... }
Document plugins
It is convenient if we could produce a macro example like how std::env! is represented.
/// Performs some meta-programming magic.
#[cfg(rustdoc)]
macro_rules! my_plugin {
($($x:ident),*) => { /* plugin */ }
}
Needed if the std doc is built with cargo
Rustc defines --cfg dox to document env!, format_args!, etc (rust-lang/rust#13255), by specifying this flag in the Makefile. If we want to use cargo to build the documentation (rust-lang/rust#19240), then this RFC is likely needed.
Alternatives
Add a cfg = [...] option to the profile sections in Cargo.toml.
Do nothing. Tell user to use cargo doc --features "documentation" as a workaround. (Requires an empty “documentation” key in the [features] section)
// Cargo.toml
...
[features]
documentation = []
// lib.rs
#[cfg(any(feature="documentation", unix)]
pub fn unix_specific_api() { ... }
// in command line
$ cargo doc --features documentation