Update syntax information for doc(auto_cfg(hide/show())) in the rustdoc book

Author: GuillaumeGomez

src/doc/rustdoc/src/unstable-features.md

@@ -850,12 +850,49 @@ pub mod futures {
 
 Then, the `unix` cfg will never be displayed into the documentation.
 
-Rustdoc currently hides `doc` and `doctest` attributes by default and reserves the right to change the list of "hidden by default" attributes.
+The syntax of `hide` is as follows: you can list as many `cfg` name as you want:
+
+```rust,ignore (nightly)
+#[doc(auto_cfg(hide(feature, target_os)))]
+```
+
+With the above example, it means that `#[cfg(feature)]` and `#[cfg(target_os)]` won't be displayed in the docs. However, `#[cfg(target_os = "linux)]` or `#[cfg(feature = "something")]` will be displayed because only the key without values was marked as hidden. if you want to hide some values, you can do:
+
+```rust,ignore (nightly)
+#[doc(auto_cfg(hide(feature, target_os, values("something", "linux"))))]
+```
+
+In this case, `#[cfg(feature = "linux")]`, `#[cfg(feature = "something")]`, `#[cfg(target_os = "something")]` and `#[cfg(target_os = "linux")]` will be hidden. All listed keys will be impacted by `values()`. You can split them by having two `hide`:
+
+```rust,ignore (nightly)
+#[doc(auto_cfg(
+    hide(feature, values("something")),
+    hide(target_os, values("linux"))))]
+```
+
+Now, only `#[cfg(feature = "something")]` and `#[cfg(target_os = "linux")]` will be hidden. If you want to hide all values of a key, you can use `any()`:
+
+```rust,ignore (nightly)
+#[doc(auto_cfg(hide(feature, values(any()))))]
+```
+
+To be noted, if you have `values()`, it will be considered the same as `values(any())`. If you want to hide when there is no value (while also hiding values at the same time), you can use `none()`:
+
+```rust,ignore (nightly)
+#[doc(auto_cfg(hide(feature, values("something", none()))))]
+```
+
+If the previous example, both `#[cfg(feature)]` and `#[cfg(feature = "something")]` will be hidden.
+
+Rustdoc currently hides `test`, `doc` and `doctest` attributes by default and reserves the right to change the list of "hidden by default" attributes.
 
 The attribute accepts only a list of identifiers or key/value items. So you can write:
 
 ```rust,ignore (nightly)
-#[doc(auto_cfg(hide(unix, doctest, feature = "something")))]
+#[doc(auto_cfg(
+    hide(unix, doctest),
+    hide(feature, values("something")),
+))]
 #[doc(auto_cfg(hide()))]
 ```
 
@@ -865,7 +902,7 @@ But you cannot write:
 #[doc(auto_cfg(hide(not(unix))))]
 ```
 
-So if we use `doc(auto_cfg(hide(unix)))`, it means it will hide all mentions of `unix`:
+So if we use `doc(auto_cfg(hide(unix)))`, it means it will hide all mentions of `unix` without a value:
 
 ```rust,ignore (nightly)
 #[cfg(unix)] // nothing displayed
@@ -919,6 +956,8 @@ The reason behind this is that `doc(auto_cfg = ...)` enables or disables the fea
 This attribute does the opposite of `#[doc(auto_cfg(hide(...)))]`: if you used `#[doc(auto_cfg(hide(...)))]` and want to revert its effect on an item and its descendants, you can use `#[doc(auto_cfg(show(...)))]`.
 It only applies to `#[doc(auto_cfg = true)]`, not to `#[doc(cfg(...))]`.
 
+It follows the same syntax rules as for `#[doc(auto_cfg(hide(...)))]`.
+
 For example:
 
 ```rust,ignore (nightly)
@@ -936,7 +975,10 @@ pub mod futures {
 The attribute accepts only a list of identifiers or key/value items. So you can write:
 
 ```rust,ignore (nightly)
-#[doc(auto_cfg(show(unix, doctest, feature = "something")))]
+#[doc(auto_cfg(
+    show(unix, doctest),
+    show(feature, values("something")),
+))]
 #[doc(auto_cfg(show()))]
 ```
 

tests/rustdoc-ui/doc-cfg-4.rs

@@ -1,4 +1,4 @@
-// Checks that you cannot have any item inside `any()` and 
+// Checks that you cannot have any item inside `any()` and `none()`.
 
 #![deny(invalid_doc_attributes)]
 #![feature(doc_cfg)]