[Pre-RFC] `rustdoc` or `cargo doc` should pass a special `--cfg rustdoc` flag


#1

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

#2

Submitted as https://github.com/rust-lang/rfcs/pull/834.