Explain how doc(cfg) and doc(auto_cfg) interacts

Author: GuillaumeGomez

text/000-rustdoc-cfgs-handling.md

@@ -227,6 +227,19 @@ pub mod desktop {
 
 [Future versions of rustdoc][boolean simplification] may simplify this display down to "available on **Windows** only."
 
+## `doc(cfg)` and `doc(auto_cfg)` used on a same item
+
+If `doc(cfg)` is used on an item while `doc(auto_cfg)` is enabled, both will be merged:
+
+```rust
+// `doc(auto_cfg)` is enabled here
+#[doc(cfg(feature = "futures-io"))]
+#[cfg(feature = "something")]
+pub mod futures {}
+```
+
+In this case, it'll display that both `feature = "futures-io"` and `feature = "something"` are required to use this module. Just like lints, users will get better control over this feature. For example if someone wants to completely override doc cfg attributes on a given item, they will be able to disable it for this item completely and then add what they want using `doc(cfg)`. An example for this is in case you have "parent" features with a lot of children and want to simplify some children `cfg` display when rendered in documentation.
+
 ### 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.