Add documentation for doc cfg

GuillaumeGomez · GuillaumeGomez · commit 4a05a528543f · 2025-03-24T23:48:56.000+01:00
diff --git a/src/doc/rustdoc/src/advanced-features.md b/src/doc/rustdoc/src/advanced-features.md
@@ -33,6 +33,204 @@ 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.
 
+## Recording what platforms or features are required for code to be present
+
+By default, rustdoc will pick the `cfg` attributes present on each item and render them in the
+generated documentation. However, if you want to tweak or completely overload this behaviour, it's
+possible with the `#[doc(auto_cfg)]` and `#[doc(cfg(...)]` attributes.
+
+### `#[doc(auto_cfg)]`
+
+This attribute can have the following forms:
+
+ * `#[doc(auto_cfg)]`
+ * `#[doc(auto_cfg = ...)]`
+ * `#[doc(auto_cfg(show(...)))]`
+ * `#[doc(auto_cfg(hide(...)))]`
+
+`#[doc(auto_cfg)]` enables the feature and is the shorter form of `#[doc(auto_cfg = true)]`.
+Enabling the feature means that the `cfg` attributes will be picked automatically by rustdoc. To be
+noted: using any form of `#[doc(auto_cfg)]` will (re-)enable the feature.
+
+If you want to disable it, you can use `#[doc(auto_cfg = false)]`.
+
+The state of the feature (whether it's enabled or disabled) is inherited by the item's children. So
+if you disable the feature on module, non of the module items will get their `cfg` picked
+automatically, unless you re-enable the feature on the items.
+
+Now about `#[doc(auto_cfg(show(...)))]` and `#[doc(auto_cfg(hide(...)))]`, they allow you to
+show/hide `cfg`s you don't want to appear in the documentation. By default, rustdoc hides the
+following `cfg` attributes: `test`, `doc` and `doctest`.
+
+You can use it as follows:
+
+```rust
+#[doc(auto_cfg(hide(unix)))]
+#[cfg(any(unix, feature = "futures-io"))]
+pub mod futures {
+    // `futures` and all its descendants won't display "unix" in their cfgs.
+}
+```
+
+And if you want to revert the hidden attributes, you can use `doc(auto_cfg(show(...)))`:
+
+```rust
+#[doc(auto_cfg(hide(unix)))]
+#[cfg(any(unix, feature = "futures-io"))]
+pub mod futures {
+    // `futures` and all its descendants won't display "unix" in their cfgs.
+    #[doc(auto_cfg(show(unix)))]
+    #[cfg(unix)] // It will be displayed for `bar`.
+    pub fn bar() {}
+
+    #[cfg(unix)] // It will not be displayed for `bar`.
+    pub fn foo() {}
+}
+```
+
+The attribute accepts only a list of identifiers or key/value items. So you can write:
+
+```rust
+#[doc(auto_cfg(hide(unix, doctest, feature = "something")))]
+#[doc(auto_cfg(hide()))]
+```
+
+But you cannot write:
+
+```rust
+#[doc(auto_cfg(hide(not(unix))))]
+```
+
+So if we use `doc(auto_cfg(hide(unix)))`, it means it will hide all mentions of `unix`:
+
+```rust
+#[cfg(unix)] // nothing displayed
+#[cfg(any(unix))] // nothing displayed
+#[cfg(any(unix, windows))] // only `windows` displayed
+```
+
+However, it only impacts the `unix` cfg, not the feature:
+
+```rust
+#[cfg(feature = "unix")] // `feature = "unix"` is displayed
+```
+
+If `cfg_auto(show(...))` and `cfg_auto(hide(...))` are used to show/hide a same cfg on a same item,
+it'll emit an error. Example:
+
+```rust
+#[doc(auto_cfg(hide(unix)))]
+#[doc(auto_cfg(show(unix)))] // Error!
+pub fn foo() {}
+```
+
+### `#[doc(cfg(...))]`
+
+This attribute provides a standardized format to override `#[cfg()]` attributes to document
+conditionally available items. Example:
+
+```rust
+// the "real" cfg condition
+#[cfg(feature = "futures-io")]
+// the `doc(cfg())` so it's displayed to the readers
+#[doc(cfg(feature = "futures-io"))]
+pub mod futures {}
+```
+
+It will display in the documentation for this module:
+
+```text
+This is supported on feature="futures-io" only.
+```
+
+You can use it to display information in generated documentation, whether or not there is a
+`#[cfg()]` attribute:
+
+```rust
+#[doc(cfg(feature = "futures-io"))]
+pub mod futures {}
+```
+
+It will be displayed exactly the same as the previous code.
+
+This attribute has the same syntax as conditional compilation, but it only causes documentation to
+be added. This means `#[doc(cfg(not(windows)))]` will not cause your docs to be hidden on
+non-windows targets, even though `#[cfg(not(windows))]` does do that.
+
+If `doc(auto_cfg)` is enabled on the item, `doc(cfg)` will override it anyway so in the two previous
+examples, even if the `doc(auto_cfg)` feature was enabled, it would still display the same thing.
+
+### (doc) cfg inheritance
+
+Rustdoc merges `cfg` attributes from parent modules to its children. For example, in this case, the
+module `non_unix` will describe the entire compatibility matrix for the module, and not just its
+directly attached information:
+
+```rust
+#[doc(cfg(any(windows, unix)))]
+pub mod desktop {
+    #[doc(cfg(not(unix)))]
+    pub mod non_unix {
+        //
+    }
+}
+```
+
+will display:
+
+```
+Available on (Windows or Unix) and non-Unix only.
+```
+
+### Re-exports and inlining
+
+`cfg` attributes of a re-export are never merged with the re-exported item(s) attributes except if
+the re-export has the `#[doc(inline)]` attribute. In this case, the `cfg` of the re-exported item
+will be merged with the re-export's.
+
+When talking about "attributes merge", we mean that if the re-export has `#[cfg(unix)]` and the
+re-exported item has `#[cfg(feature = "foo")]`, you will only see `cfg(unix)` on the re-export and
+only `cfg(feature = "foo")` on the re-exported item, unless the re-export has `#[doc(inline)]`, then
+you will only see the re-exported item with both `cfg(unix)` and `cfg(feature = "foo")`.
+
+Example:
+
+```rust
+#[doc(cfg(any(windows, unix)))]
+pub mod desktop {
+    #[doc(cfg(not(unix)))]
+    pub mod non_unix {
+        // code
+    }
+}
+
+#[doc(cfg(target_os = "freebsd"))]
+pub use desktop::non_unix as non_unix_desktop;
+#[doc(cfg(target_os = "macos"))]
+#[doc(inline)]
+pub use desktop::non_unix as inlined_non_unix_desktop;
+```
+
+In this example, `non_unix_desktop` will only display `cfg(target_os = "freeebsd")` and not display
+any `cfg` from `desktop::non_unix`.
+
+On the contrary, `inlined_non_unix_desktop` will have cfgs from both the re-export and the
+re-exported item.
+
+So that also means that if a crate re-exports a foreign item, unless it has `#[doc(inline)]`, the
+`cfg` and `doc(cfg)` attributes will not be visible:
+
+```rust
+// dep:
+#[cfg(feature = "a")]
+pub struct S;
+
+// crate using dep:
+
+// There will be no mention of `feature = "a"` in the documentation.
+pub use dep::S as Y;
+```
+
 ### Interactions between platform-specific docs
 
 Rustdoc does not have a magic way to compile documentation 'as-if' you'd run it once for each
diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md
@@ -56,88 +56,6 @@ It is also not emitted for foreign items, aliases, extern crates and imports.
 These features operate by extending the `#[doc]` attribute, and thus can be caught by the compiler
 and enabled with a `#![feature(...)]` attribute in your crate.
 
-### `#[doc(cfg)]`: Recording what platforms or features are required for code to be present
-
- * Tracking issue: [#43781](https://github.com/rust-lang/rust/issues/43781)
-
-You can use `#[doc(cfg(...))]` to tell Rustdoc exactly which platform items appear on.
-This has two effects:
-
-1. doctests will only run on the appropriate platforms, and
-2. When Rustdoc renders documentation for that item, it will be accompanied by a banner explaining
-   that the item is only available on certain platforms.
-
-`#[doc(cfg)]` is intended to be used alongside [`#[cfg(doc)]`][cfg-doc].
-For example, `#[cfg(any(windows, doc))]` will preserve the item either on Windows or during the
-documentation process. Then, adding a new attribute `#[doc(cfg(windows))]` will tell Rustdoc that
-the item is supposed to be used on Windows. For example:
-
-```rust
-#![feature(doc_cfg)]
-
-/// Token struct that can only be used on Windows.
-#[cfg(any(windows, doc))]
-#[doc(cfg(windows))]
-pub struct WindowsToken;
-
-/// Token struct that can only be used on Unix.
-#[cfg(any(unix, doc))]
-#[doc(cfg(unix))]
-pub struct UnixToken;
-
-/// Token struct that is only available with the `serde` feature
-#[cfg(feature = "serde")]
-#[doc(cfg(feature = "serde"))]
-#[derive(serde::Deserialize)]
-pub struct SerdeToken;
-```
-
-In this sample, the tokens will only appear on their respective platforms, but they will both appear
-in documentation.
-
-`#[doc(cfg(...))]` was introduced to be used by the standard library and currently requires the
-`#![feature(doc_cfg)]` feature gate. For more information, see [its chapter in the Unstable
-Book][unstable-doc-cfg] and [its tracking issue][issue-doc-cfg].
-
-### `doc_auto_cfg`: Automatically generate `#[doc(cfg)]`
-
- * Tracking issue: [#43781](https://github.com/rust-lang/rust/issues/43781)
-
-`doc_auto_cfg` is an extension to the `#[doc(cfg)]` feature. With it, you don't need to add
-`#[doc(cfg(...)]` anymore unless you want to override the default behaviour. So if we take the
-previous source code:
-
-```rust
-#![feature(doc_auto_cfg)]
-
-/// 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;
-
-/// Token struct that is only available with the `serde` feature
-#[cfg(feature = "serde")]
-#[derive(serde::Deserialize)]
-pub struct SerdeToken;
-```
-
-It'll render almost the same, the difference being that `doc` will also be displayed. To fix this,
-you can use `doc_cfg_hide`:
-
-```rust
-#![feature(doc_cfg_hide)]
-#![doc(cfg_hide(doc))]
-```
-
-And `doc` won't show up anymore!
-
-[cfg-doc]: ./advanced-features.md
-[unstable-doc-cfg]: ../unstable-book/language-features/doc-cfg.html
-[issue-doc-cfg]: https://github.com/rust-lang/rust/issues/43781
-
 ### Adding your trait to the "Notable traits" dialog
 
  * Tracking issue: [#45040](https://github.com/rust-lang/rust/issues/45040)
