Rollup merge of rust-lang#61351 - GuillaumeGomez:stabilize-cfg-rustdoc, r=QuietMisdreavus

Stabilize cfg(doc)

cc rust-lang#43781.

Author: Centril

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)

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.

src/librustdoc/core.rs

@@ -250,7 +250,7 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt
 
     let extern_names: Vec<String> = 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());

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)]

src/libsyntax_pos/symbol.rs

@@ -627,7 +627,6 @@ symbols! {
         rustc_test_marker,
         rustc_then_this_would_need,
         rustc_variance,
-        rustdoc,
         rustfmt,
         rust_eh_personality,
         rust_eh_unwind_resume,

src/test/ui/cfg-rustdoc.rs

@@ -0,0 +1,6 @@
+#[cfg(doc)]
+pub struct Foo;
+
+fn main() {
+    let f = Foo; //~ ERROR
+}

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`.