6 files changed, 46 insertions, 17 deletions
diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md
index 80ac405eb2f..3aaac9268ff 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 a13a4475ef0..a9f41633f30 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 00000000000..a8e0c87eff8
--- /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 00000000000..c687d186989
--- /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 9830503a8ca..00000000000
--- 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 26a1f4decf4..00000000000
--- 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`.