Update 000-rustdoc-cfgs-handling.md

text/000-rustdoc-cfgs-handling.md

@@ -47,7 +47,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 +58,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,12 +94,14 @@ 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 {
+    // All descendants of `futures` won't display "doc" in their cfgs.
+}
 ```
 
 Then, the `doc` cfg will never be displayed into the documentation.