diff --git a/src/doc/rustdoc/src/SUMMARY.md b/src/doc/rustdoc/src/SUMMARY.md index d4202f5b367ab..f982863e67b94 100644 --- a/src/doc/rustdoc/src/SUMMARY.md +++ b/src/doc/rustdoc/src/SUMMARY.md @@ -7,4 +7,5 @@ - [Documentation tests](documentation-tests.md) - [Lints](lints.md) - [Passes](passes.md) +- [Advanced Features](advanced-features.md) - [Unstable features](unstable-features.md) diff --git a/src/doc/rustdoc/src/advanced-features.md b/src/doc/rustdoc/src/advanced-features.md new file mode 100644 index 0000000000000..47bef3cdde187 --- /dev/null +++ b/src/doc/rustdoc/src/advanced-features.md @@ -0,0 +1,34 @@ +# Advanced Features + +The features listed on this page fall outside the rest of the main categories. + +## `#[cfg(doc)]`: Documenting platform-/feature-specific information + +For conditional compilation, Rustdoc treats your crate the same way the compiler does: Only things +from the host target are available (or from the given `--target` if present), and everything else is +"filtered out" from the crate. This can cause problems if your crate is providing different things +on different targets and you want your documentation to reflect all the available items you +provide. + +If you want to make sure an item is seen by Rustdoc regardless of what platform it's targeting, +you can apply `#[cfg(doc)]` to it. Rustdoc sets this whenever it's building documentation, so +anything that uses that flag will make it into documentation it generates. To apply this to an item +with other `#[cfg]` filters on it, you can write something like `#[cfg(any(windows, doc))]`. +This will preserve the item either when built normally on Windows, or when being documented +anywhere. + +Please note that this feature is not passed to doctests. + +Example: + +```rust +/// Token struct that can only be used on Windows. +#[cfg(any(windows, doc))] +pub struct WindowsToken; +/// Token struct that can only be used on Unix. +#[cfg(any(unix, doc))] +pub struct UnixToken; +``` + +Here, the respective tokens can only be used by dependent crates on their respective platforms, but +they will both appear in documentation. diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index 2b4ac7676fade..612f3c69871d7 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -250,7 +250,7 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt let extern_names: Vec = externs.iter().map(|(s,_)| s).cloned().collect(); - // Add the rustdoc cfg into the doc build. + // Add the doc cfg into the doc build. cfgs.push("doc".to_string()); let cpath = Some(input.clone()); diff --git a/src/libsyntax/feature_gate/builtin_attrs.rs b/src/libsyntax/feature_gate/builtin_attrs.rs index a13a4475ef01c..a9f41633f30fd 100644 --- a/src/libsyntax/feature_gate/builtin_attrs.rs +++ b/src/libsyntax/feature_gate/builtin_attrs.rs @@ -30,7 +30,6 @@ const GATED_CFGS: &[(Symbol, Symbol, GateFn)] = &[ (sym::target_thread_local, sym::cfg_target_thread_local, cfg_fn!(cfg_target_thread_local)), (sym::target_has_atomic, sym::cfg_target_has_atomic, cfg_fn!(cfg_target_has_atomic)), (sym::target_has_atomic_load_store, sym::cfg_target_has_atomic, cfg_fn!(cfg_target_has_atomic)), - (sym::doc, sym::doc_cfg, cfg_fn!(doc_cfg)), ]; #[derive(Debug)] diff --git a/src/libsyntax_pos/symbol.rs b/src/libsyntax_pos/symbol.rs index 1139bf67a36d0..cab82f8c61b11 100644 --- a/src/libsyntax_pos/symbol.rs +++ b/src/libsyntax_pos/symbol.rs @@ -624,7 +624,6 @@ symbols! { rustc_test_marker, rustc_then_this_would_need, rustc_variance, - rustdoc, rustfmt, rust_eh_personality, rust_eh_unwind_resume, diff --git a/src/test/ui/cfg-rustdoc.rs b/src/test/ui/cfg-rustdoc.rs new file mode 100644 index 0000000000000..dd8e1ed97c4d2 --- /dev/null +++ b/src/test/ui/cfg-rustdoc.rs @@ -0,0 +1,6 @@ +#[cfg(doc)] +pub struct Foo; + +fn main() { + let f = Foo; //~ ERROR +} diff --git a/src/test/ui/cfg-rustdoc.stderr b/src/test/ui/cfg-rustdoc.stderr new file mode 100644 index 0000000000000..c687d186989c0 --- /dev/null +++ b/src/test/ui/cfg-rustdoc.stderr @@ -0,0 +1,9 @@ +error[E0425]: cannot find value `Foo` in this scope + --> $DIR/cfg-rustdoc.rs:5:13 + | +LL | let f = Foo; + | ^^^ not found in this scope + +error: aborting due to previous error + +For more information about this error, try `rustc --explain E0425`. diff --git a/src/test/ui/feature-gates/feature-gate-doc_cfg-cfg-rustdoc.rs b/src/test/ui/feature-gates/feature-gate-doc_cfg-cfg-rustdoc.rs deleted file mode 100644 index 9830503a8cac6..0000000000000 --- a/src/test/ui/feature-gates/feature-gate-doc_cfg-cfg-rustdoc.rs +++ /dev/null @@ -1,4 +0,0 @@ -#[cfg(doc)] //~ ERROR: `cfg(doc)` is experimental and subject to change -pub struct SomeStruct; - -fn main() {} diff --git a/src/test/ui/feature-gates/feature-gate-doc_cfg-cfg-rustdoc.stderr b/src/test/ui/feature-gates/feature-gate-doc_cfg-cfg-rustdoc.stderr deleted file mode 100644 index 26a1f4decf4cf..0000000000000 --- a/src/test/ui/feature-gates/feature-gate-doc_cfg-cfg-rustdoc.stderr +++ /dev/null @@ -1,12 +0,0 @@ -error[E0658]: `cfg(doc)` is experimental and subject to change - --> $DIR/feature-gate-doc_cfg-cfg-rustdoc.rs:1:7 - | -LL | #[cfg(doc)] - | ^^^ - | - = note: for more information, see https://github.com/rust-lang/rust/issues/43781 - = help: add `#![feature(doc_cfg)]` to the crate attributes to enable - -error: aborting due to previous error - -For more information about this error, try `rustc --explain E0658`.