From 086c8d3db71c7d448b55536d6862f177ad7f60dd Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Fri, 6 Sep 2019 10:51:52 +0200 Subject: [PATCH 1/3] Stabilize cfg rustdoc --- src/doc/rustdoc/src/the-doc-attribute.md | 31 +++++++++++++++++++ src/libsyntax/feature_gate/builtin_attrs.rs | 1 - src/test/ui/cfg-rustdoc.rs | 6 ++++ src/test/ui/cfg-rustdoc.stderr | 9 ++++++ .../feature-gate-doc_cfg-cfg-rustdoc.rs | 4 --- .../feature-gate-doc_cfg-cfg-rustdoc.stderr | 12 ------- 6 files changed, 46 insertions(+), 17 deletions(-) create mode 100644 src/test/ui/cfg-rustdoc.rs create mode 100644 src/test/ui/cfg-rustdoc.stderr delete mode 100644 src/test/ui/feature-gates/feature-gate-doc_cfg-cfg-rustdoc.rs delete mode 100644 src/test/ui/feature-gates/feature-gate-doc_cfg-cfg-rustdoc.stderr diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md index 80ac405eb2f2a..3aaac9268ffcf 100644 --- a/src/doc/rustdoc/src/the-doc-attribute.md +++ b/src/doc/rustdoc/src/the-doc-attribute.md @@ -214,3 +214,34 @@ the `strip-hidden` pass is removed. Since primitive types are defined in the compiler, there's no place to attach documentation attributes. This attribute is used by the standard library to provide a way to generate documentation for primitive types. + +## `#[cfg(rustdoc)]`: 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(rustdoc)]` 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, rustdoc))]`. +This will preserve the item either when built normally on Windows, or when being documented +anywhere. + +Please note that this feature won't be passed when building doctests. + +Example: + +```rust +/// Token struct that can only be used on Windows. +#[cfg(any(windows, rustdoc))] +pub struct WindowsToken; +/// Token struct that can only be used on Unix. +#[cfg(any(unix, rustdoc))] +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/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/test/ui/cfg-rustdoc.rs b/src/test/ui/cfg-rustdoc.rs new file mode 100644 index 0000000000000..a8e0c87eff851 --- /dev/null +++ b/src/test/ui/cfg-rustdoc.rs @@ -0,0 +1,6 @@ +#[cfg(rustdoc)] +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`. From a056bf9714fca847494ee6aa6025acb1a7fdd852 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 6 Nov 2019 14:48:10 +0100 Subject: [PATCH 2/3] Rename the cfg attribute from rustdoc to doc --- src/doc/rustdoc/src/the-doc-attribute.md | 10 +++++----- src/librustdoc/core.rs | 2 +- src/libsyntax_pos/symbol.rs | 1 - src/test/ui/cfg-rustdoc.rs | 2 +- 4 files changed, 7 insertions(+), 8 deletions(-) diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md index 3aaac9268ffcf..5fac0bddc3bfb 100644 --- a/src/doc/rustdoc/src/the-doc-attribute.md +++ b/src/doc/rustdoc/src/the-doc-attribute.md @@ -215,7 +215,7 @@ Since primitive types are defined in the compiler, there's no place to attach do attributes. This attribute is used by the standard library to provide a way to generate documentation for primitive types. -## `#[cfg(rustdoc)]`: Documenting platform-/feature-specific information +## `#[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 @@ -224,9 +224,9 @@ on different targets and you want your documentation to reflect all the availabl provide. If you want to make sure an item is seen by Rustdoc regardless of what platform it's targeting, -you can apply `#[cfg(rustdoc)]` to it. Rustdoc sets this whenever it's building documentation, so +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, rustdoc))]`. +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. @@ -236,10 +236,10 @@ Example: ```rust /// Token struct that can only be used on Windows. -#[cfg(any(windows, rustdoc))] +#[cfg(any(windows, doc))] pub struct WindowsToken; /// Token struct that can only be used on Unix. -#[cfg(any(unix, rustdoc))] +#[cfg(any(unix, doc))] pub struct UnixToken; ``` 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_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 index a8e0c87eff851..dd8e1ed97c4d2 100644 --- a/src/test/ui/cfg-rustdoc.rs +++ b/src/test/ui/cfg-rustdoc.rs @@ -1,4 +1,4 @@ -#[cfg(rustdoc)] +#[cfg(doc)] pub struct Foo; fn main() { From 0d7a7b554771daee7b08caa8c49544910948c915 Mon Sep 17 00:00:00 2001 From: QuietMisdreavus Date: Wed, 6 Nov 2019 11:10:21 -0600 Subject: [PATCH 3/3] move cfg(doc) docs into a separate page --- src/doc/rustdoc/src/SUMMARY.md | 1 + src/doc/rustdoc/src/advanced-features.md | 34 ++++++++++++++++++++++++ src/doc/rustdoc/src/the-doc-attribute.md | 31 --------------------- 3 files changed, 35 insertions(+), 31 deletions(-) create mode 100644 src/doc/rustdoc/src/advanced-features.md 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/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md index 5fac0bddc3bfb..80ac405eb2f2a 100644 --- a/src/doc/rustdoc/src/the-doc-attribute.md +++ b/src/doc/rustdoc/src/the-doc-attribute.md @@ -214,34 +214,3 @@ the `strip-hidden` pass is removed. Since primitive types are defined in the compiler, there's no place to attach documentation attributes. This attribute is used by the standard library to provide a way to generate documentation for primitive types. - -## `#[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 won't be passed when building 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.