Greatly extend explanations on strip_hidden items

Co-authored-by: Michael Howell <michael@notriddle.com>

diff --git a/src/librustdoc/passes/strip_hidden.rs b/src/librustdoc/passes/strip_hidden.rs
index a8012185a6d148e48e508ba15191d549a220133f..533e2ce46ddd844acb4691f68b5591007c45fef3 100644 (file)
--- a/src/librustdoc/passes/strip_hidden.rs
+++ b/src/librustdoc/passes/strip_hidden.rs
@@ -38,7 +38,14 @@ impl<'a> DocFolder for Stripper<'a> {
     fn fold_item(&mut self, i: Item) -> Option<Item> {
         if i.attrs.lists(sym::doc).has_word(sym::hidden) {
             debug!("strip_hidden: stripping {:?} {:?}", i.type_(), i.name);
-            // use a dedicated hidden item for given item type if any
+            // Use a dedicated hidden item for fields, variants, and modules.
+            // We need to keep private fields and variants, so that the docs
+            // can show a placeholder "// some variants omitted". We need to keep
+            // private modules, because they can contain impl blocks, and impl
+            // block privacy is inherited from the type and trait, not from the
+            // module it's defined in. Both of these are marked "stripped," and
+            // not included in the final docs, but since they still have an effect
+            // on the final doc, cannot be completely removed from the Clean IR.
             match *i.kind {
                 clean::StructFieldItem(..) | clean::ModuleItem(..) | clean::VariantItem(..) => {
                     // We need to recurse into stripped modules to