From: QuietMisdreavus <grey@quietmisdreavus.net>
Date: Wed, 6 Nov 2019 17:10:21 +0000 (-0600)
Subject: move cfg(doc) docs into a separate page
X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=0d7a7b554771daee7b08caa8c49544910948c915;p=rust.git

move cfg(doc) docs into a separate page
---

diff --git a/src/doc/rustdoc/src/SUMMARY.md b/src/doc/rustdoc/src/SUMMARY.md
index d4202f5b367..f982863e67b 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 00000000000..47bef3cdde1
--- /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 5fac0bddc3b..80ac405eb2f 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.