Update 000-rustdoc-cfgs-handling.md

text/000-rustdoc-cfgs-handling.md

@@ -26,10 +26,11 @@ This RFC proposes to add the following attributes:
  * `#[doc(cfg(...))]`
  * `#[doc(auto_cfg)]`/`#[doc(no_auto_cfg)]`
  * `#[doc(cfg_hide(...))]`
+ * `#[doc(cfg_show(...))]`
 
 ### `#[doc(cfg(...))]`
 
-This attribute allows to manually add under which conditions an item is available to the documentation readers. Example:
+This attribute allows to manually add under which conditions an item is available and to display it in the documentation. Example:
 
 ```rust
 // the "real" cfg condition
@@ -47,7 +48,7 @@ This attribute works on modules and on items but cannot be used at the crate roo
 
 ### `#[doc(auto_cfg)]`/`#[doc(no_auto_cfg)]`
 
-By default, rustdoc will automatically retrieve the `cfg` information on items, no need for users to use `#[doc(cfg(...))]`. So if we take back the previous example:
+By default, `#[doc(auto_cfg)]` will be enabled, meaning that rustdoc will automatically retrieve the `cfg` information on items, no need for users to use `#[doc(cfg(...))]`. So if we take back the previous example:
 
 ```rust
 #[cfg(feature = "futures-io")]
@@ -58,7 +59,24 @@ No need to "duplicate" the `cfg` into a `doc(cfg())` to make it displayed to the
 
 So by default, `#[doc(auto_cfg)]` is enabled. However, for some reasons, you might want to disable this behaviour on a given item/module or on the whole crate. To do so, you can use `#[doc(no_auto_cfg)]`.
 
-Both `#[doc(auto_cfg)]` and `#[doc(no_auto_cfg)]` attributes impact all there descendants. You can then enable/disable them by using the opposite attribute on a given item.
+Both `#[doc(auto_cfg)]` and `#[doc(no_auto_cfg)]` attributes impact all there descendants. You can then enable/disable them by using the opposite attribute on a given item. They can be used as follows:
+
+```rust
+// As an inner attribute, all this module's descendants will have this feature
+// enabled.
+#![doc(auto_cfg)]
+
+// As an outer attribute, so in this case, `foo` and all its descendants won't have
+// the `auto_cfg` feature enabled.
+#[doc(no_auto_cfg)] 
+pub mod foo {
+    // We re-enable the feature on `Bar` and on all its descendants.
+    #[doc(auto_cfg)]
+    pub struct Bar {
+        pub f: u32,
+    }
+}
+```
 
 As mentioned, both attributes can be used on modules, items and crate root level.
 
@@ -77,34 +95,50 @@ It currently displays both `doc` and `feature = "futures-io"` into the documenta
 #![doc(cfg_hide(doc))]
 ```
 
-Or directly on the item as it covers any of the item's children:
+Or directly on a given item/module as it covers any of the item's descendants:
 
 ```rust
 #[doc(cfg_hide(doc))]
 #[cfg(any(doc, feature = "futures-io"))]
-pub mod futures {}
+pub mod futures {
+    // `futures` and all its descendants won't display "doc" in their cfgs.
+}
 ```
 
 Then, the `doc` cfg will never be displayed into the documentation.
 
+### `#[doc(cfg_show(...))]`
+
+This attribute does the opposite of `#[doc(cfg_hide(...))]`: if you used `#[doc(cfg_hide(...))]` and want to revert its effect on an item and its descendants, you can use `#[doc(cfg_show(...))]`:
+
+```rust
+#[doc(cfg_hide(doc))]
+#[cfg(any(doc, feature = "futures-io"))]
+pub mod futures {
+    // `futures` and all its descendants won't display "doc" in their cfgs.
+    #[doc(cfg_show(doc))]
+    pub mod child {
+        // `child` and all its descendants will display "doc" in their cfgs.
+    }
+}
+```
+
+This attribute cannot be used at the crate level.
+
 # Reference-level explanation
 [reference-level-explanation]: #reference-level-explanation
 
-TO BE DONE.
+This feature adds attributes only used by rustdoc when generating documentation to generate the extra information on generated HTML pages.
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+A potential drawback is that it adds more attributes, making documentation more complex.
 
 # Rationale and alternatives
 [rationale-and-alternatives]: #rationale-and-alternatives
 
-TO BE DONE.
-
-# Prior Art
-[prior-art]: #prior-art
 
-TO BE DONE.
 
 # Unresolved questions
 [unresolved-questions]: #unresolved-questions
-
-### Should we add an attribute to revert `#[doc(cfg_hide(...))`?
-
-It would make sense to think that in some locations, someone might want to not hide a given `cfg`.