Add code documentation, improve code and improve error message

2 files changed, 22 insertions, 5 deletions

diff --git a/src/librustdoc/clean/types.rs b/src/librustdoc/clean/types.rs
index 2ec97a57087..545f1ef6da4 100644
--- a/src/librustdoc/clean/types.rs
+++ b/src/librustdoc/clean/types.rs
@@ -922,11 +922,19 @@ pub(crate) fn hir_attr_lists<'a, I: IntoIterator<Item = &'a hir::Attribute>>(
         .flatten()
 }
 
+/// This type keeps track of (doc) cfg information as we go down the item tree.
 #[derive(Clone, Debug)]
 pub(crate) struct CfgInfo {
+    /// List of `doc(auto_cfg(hide(...)))` cfgs.
     hidden_cfg: FxHashSet<Cfg>,
+    /// Current computed `cfg`. Each time we enter a new item, this field is updated as well while
+    /// taking into account the `hidden_cfg` information.
     current_cfg: Cfg,
+    /// Whether the `doc(auto_cfg())` feature is enabled or not at this point.
     auto_cfg_active: bool,
+    /// If the parent item used `doc(cfg(...))`, then we don't want to overwrite `current_cfg`,
+    /// instead we will concatenate with it. However, if it's not the case, we need to overwrite
+    /// `current_cfg`.
     parent_is_doc_cfg: bool,
 }
 
@@ -962,6 +970,11 @@ fn show_hide_show_conflict_error(
     diag.emit();
 }
 
+/// This function checks if a same `cfg` is present in both `auto_cfg(hide(...))` and
+/// `auto_cfg(show(...))` on the same item. If so, it emits an error.
+///
+/// Because we go through a list of `cfg`s, we keep track of the `cfg`s we saw in `new_show_attrs`
+/// and in `new_hide_attrs` arguments.
 fn handle_auto_cfg_hide_show(
     tcx: TyCtxt<'_>,
     cfg_info: &mut CfgInfo,
diff --git a/src/librustdoc/passes/propagate_doc_cfg.rs b/src/librustdoc/passes/propagate_doc_cfg.rs
index 802f2fbe569..ea77065ac07 100644
--- a/src/librustdoc/passes/propagate_doc_cfg.rs
+++ b/src/librustdoc/passes/propagate_doc_cfg.rs
@@ -30,7 +30,8 @@ struct CfgPropagator<'a, 'tcx> {
     cfg_info: CfgInfo,
 }
 
-fn should_retain(token: &TokenTree) -> bool {
+/// Returns true if the provided `token` is a `cfg` ident.
+fn is_cfg_token(token: &TokenTree) -> bool {
     // We only keep `doc(cfg)` items.
     matches!(
         token,
@@ -47,7 +48,9 @@ fn should_retain(token: &TokenTree) -> bool {
     )
 }
 
-fn filter_tokens_from_list(args_tokens: &TokenStream) -> Vec<TokenTree> {
+/// We only want to keep `#[cfg()]` and `#[doc(cfg())]` attributes so we rebuild a vec of
+/// `TokenTree` with only the tokens we're interested into.
+fn filter_non_cfg_tokens_from_list(args_tokens: &TokenStream) -> Vec<TokenTree> {
     let mut tokens = Vec::with_capacity(args_tokens.len());
     let mut skip_next_delimited = false;
     for token in args_tokens.iter() {
@@ -58,7 +61,7 @@ fn filter_tokens_from_list(args_tokens: &TokenStream) -> Vec<TokenTree> {
                 }
                 skip_next_delimited = false;
             }
-            token if should_retain(token) => {
+            token if is_cfg_token(token) => {
                 skip_next_delimited = false;
                 tokens.push(token.clone());
             }
@@ -70,7 +73,8 @@ fn filter_tokens_from_list(args_tokens: &TokenStream) -> Vec<TokenTree> {
     tokens
 }
 
-// We only care about `#[cfg()]` and `#[doc(cfg())]`, we discard everything else.
+/// This function goes through the attributes list (`new_attrs`) and extract the `cfg` tokens from
+/// it and put them into `attrs`.
 fn add_only_cfg_attributes(attrs: &mut Vec<Attribute>, new_attrs: &[Attribute]) {
     for attr in new_attrs {
         if attr.is_doc_comment() {
@@ -84,7 +88,7 @@ fn add_only_cfg_attributes(attrs: &mut Vec<Attribute>, new_attrs: &[Attribute])
             if ident == sym::doc
                 && let AttrArgs::Delimited(args) = &mut normal.args
             {
-                let tokens = filter_tokens_from_list(&args.tokens);
+                let tokens = filter_non_cfg_tokens_from_list(&args.tokens);
                 args.tokens = TokenStream::new(tokens);
                 attrs.push(attr);
             } else if ident == sym::cfg_trace {