Stabilize cfg rustdoc

[rust.git] / src / doc / rustdoc / src / the-doc-attribute.md

diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md
index b165c5a6b3b937fa6cd3ca1c5925e15cad6b06ef..3aaac9268ffcf38cc76fcb0fcf73c8726bd0350d 100644 (file)
--- a/src/doc/rustdoc/src/the-doc-attribute.md
+++ b/src/doc/rustdoc/src/the-doc-attribute.md
@@ -202,7 +202,7 @@ mod bar {
 Now we'll have a `Re-exports` line, and `Bar` will not link to anywhere.
 
 One special case: In Rust 2018 and later, if you `pub use` one of your dependencies, `rustdoc` will
-not eagerly inline it as a module unless you add `#[doc(inline)}`.
+not eagerly inline it as a module unless you add `#[doc(inline)]`.
 
 ## `#[doc(hidden)]`
 
@@ -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.