From 0cf90ad53c59c73c49742075021204712c9b89f1 Mon Sep 17 00:00:00 2001
From: Aaron Hill <aa1ronham@gmail.com>
Date: Sun, 25 Oct 2020 13:25:49 -0400
Subject: [PATCH 1/2] Lint doc comments on inner items

---
 compiler/rustc_lint/src/builtin.rs | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/compiler/rustc_lint/src/builtin.rs b/compiler/rustc_lint/src/builtin.rs
index e5f66611d0f9b..a964950f1df1b 100644
--- a/compiler/rustc_lint/src/builtin.rs
+++ b/compiler/rustc_lint/src/builtin.rs
@@ -994,8 +994,7 @@ impl EarlyLintPass for UnusedDocComment {
     fn check_stmt(&mut self, cx: &EarlyContext<'_>, stmt: &ast::Stmt) {
         let kind = match stmt.kind {
             ast::StmtKind::Local(..) => "statements",
-            // Disabled pending discussion in #78306
-            ast::StmtKind::Item(..) => return,
+            ast::StmtKind::Item(..) => "inner items",
             // expressions will be reported by `check_expr`.
             ast::StmtKind::Empty
             | ast::StmtKind::Semi(_)

From d12ea6eb0d25c954555654aa20a4494fe4807592 Mon Sep 17 00:00:00 2001
From: Aaron Hill <aa1ronham@gmail.com>
Date: Fri, 23 Oct 2020 18:33:59 -0400
Subject: [PATCH 2/2] Convert unused doc comments to regular comments

---
 compiler/rustc_ast/src/util/comments.rs       |  4 +-
 compiler/rustc_ast_lowering/src/lib.rs        | 10 +--
 compiler/rustc_errors/src/emitter.rs          |  2 +-
 compiler/rustc_index/src/bit_set.rs           |  2 +-
 compiler/rustc_lint/src/builtin.rs            | 20 ++---
 compiler/rustc_middle/src/mir/query.rs        |  6 +-
 compiler/rustc_mir/src/interpret/operand.rs   |  2 +-
 .../rustc_mir/src/transform/simplify_try.rs   | 10 +--
 .../src/thir/pattern/_match.rs                |  6 +-
 .../rustc_parse/src/parser/nonterminal.rs     |  2 +-
 compiler/rustc_passes/src/region.rs           | 80 +++++++++----------
 compiler/rustc_resolve/src/imports.rs         |  2 +-
 .../src/traits/error_reporting/mod.rs         |  4 +-
 library/alloc/src/collections/vec_deque.rs    |  8 +-
 library/alloc/src/vec.rs                      |  4 +-
 library/alloc/tests/vec.rs                    |  4 +-
 library/core/src/intrinsics.rs                |  3 +-
 library/core/src/iter/mod.rs                  |  2 +-
 library/core/src/mem/maybe_uninit.rs          |  2 +-
 library/core/src/panic.rs                     |  4 +-
 library/core/src/ptr/mod.rs                   | 28 +++----
 library/core/src/time.rs                      | 20 ++---
 library/proc_macro/src/bridge/scoped_cell.rs  |  6 +-
 library/std/src/io/buffered/bufwriter.rs      |  6 +-
 library/std/src/keyword_docs.rs               | 14 ++--
 library/std/src/net/ip.rs                     |  2 +-
 library/std/src/net/parser.rs                 | 10 +--
 src/librustdoc/clean/types.rs                 | 20 ++---
 src/librustdoc/html/render/mod.rs             |  2 +-
 29 files changed, 143 insertions(+), 142 deletions(-)

diff --git a/compiler/rustc_ast/src/util/comments.rs b/compiler/rustc_ast/src/util/comments.rs
index e97c8cc4562f6..7b47cc5a6982f 100644
--- a/compiler/rustc_ast/src/util/comments.rs
+++ b/compiler/rustc_ast/src/util/comments.rs
@@ -26,7 +26,7 @@ pub struct Comment {
 /// Makes a doc string more presentable to users.
 /// Used by rustdoc and perhaps other tools, but not by rustc.
 pub fn beautify_doc_string(data: Symbol) -> String {
-    /// remove whitespace-only lines from the start/end of lines
+    // remove whitespace-only lines from the start/end of lines
     fn vertical_trim(lines: Vec<String>) -> Vec<String> {
         let mut i = 0;
         let mut j = lines.len();
@@ -50,7 +50,7 @@ pub fn beautify_doc_string(data: Symbol) -> String {
         lines[i..j].to_vec()
     }
 
-    /// remove a "[ \t]*\*" block from each line, if possible
+    // remove a "[ \t]*\*" block from each line, if possible
     fn horizontal_trim(lines: Vec<String>) -> Vec<String> {
         let mut i = usize::MAX;
         let mut can_trim = true;
diff --git a/compiler/rustc_ast_lowering/src/lib.rs b/compiler/rustc_ast_lowering/src/lib.rs
index a3f046986c014..488fd6dffa3d2 100644
--- a/compiler/rustc_ast_lowering/src/lib.rs
+++ b/compiler/rustc_ast_lowering/src/lib.rs
@@ -419,11 +419,11 @@ impl Visitor<'_> for ImplTraitTypeIdVisitor<'_> {
 
 impl<'a, 'hir> LoweringContext<'a, 'hir> {
     fn lower_crate(mut self, c: &Crate) -> hir::Crate<'hir> {
-        /// Full-crate AST visitor that inserts into a fresh
-        /// `LoweringContext` any information that may be
-        /// needed from arbitrary locations in the crate,
-        /// e.g., the number of lifetime generic parameters
-        /// declared for every type and trait definition.
+        // Full-crate AST visitor that inserts into a fresh
+        // `LoweringContext` any information that may be
+        // needed from arbitrary locations in the crate,
+        // e.g., the number of lifetime generic parameters
+        // declared for every type and trait definition.
         struct MiscCollector<'tcx, 'lowering, 'hir> {
             lctx: &'tcx mut LoweringContext<'lowering, 'hir>,
             hir_id_owner: Option<NodeId>,
diff --git a/compiler/rustc_errors/src/emitter.rs b/compiler/rustc_errors/src/emitter.rs
index b5155f8e910d7..feff25cbf1bae 100644
--- a/compiler/rustc_errors/src/emitter.rs
+++ b/compiler/rustc_errors/src/emitter.rs
@@ -1160,7 +1160,7 @@ impl EmitterWriter {
         //    `max_line_num_len`
         let padding = " ".repeat(padding + label.len() + 5);
 
-        /// Returns `override` if it is present and `style` is `NoStyle` or `style` otherwise
+        // Returns `override` if it is present and `style` is `NoStyle` or `style` otherwise
         fn style_or_override(style: Style, override_: Option<Style>) -> Style {
             match (style, override_) {
                 (Style::NoStyle, Some(override_)) => override_,
diff --git a/compiler/rustc_index/src/bit_set.rs b/compiler/rustc_index/src/bit_set.rs
index 8e00e54650df0..8be7abf1b5f8e 100644
--- a/compiler/rustc_index/src/bit_set.rs
+++ b/compiler/rustc_index/src/bit_set.rs
@@ -900,7 +900,7 @@ impl<R: Idx, C: Idx> BitMatrix<R, C> {
 
 impl<R: Idx, C: Idx> fmt::Debug for BitMatrix<R, C> {
     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
-        /// Forces its contents to print in regular mode instead of alternate mode.
+        // Forces its contents to print in regular mode instead of alternate mode.
         struct OneLinePrinter<T>(T);
         impl<T: fmt::Debug> fmt::Debug for OneLinePrinter<T> {
             fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
diff --git a/compiler/rustc_lint/src/builtin.rs b/compiler/rustc_lint/src/builtin.rs
index a964950f1df1b..73678110462c0 100644
--- a/compiler/rustc_lint/src/builtin.rs
+++ b/compiler/rustc_lint/src/builtin.rs
@@ -1658,8 +1658,8 @@ impl EarlyLintPass for EllipsisInclusiveRangePatterns {
 
         use self::ast::{PatKind, RangeSyntax::DotDotDot};
 
-        /// If `pat` is a `...` pattern, return the start and end of the range, as well as the span
-        /// corresponding to the ellipsis.
+        // If `pat` is a `...` pattern, return the start and end of the range, as well as the span
+        // corresponding to the ellipsis.
         fn matches_ellipsis_pat(pat: &ast::Pat) -> Option<(Option<&Expr>, &Expr, Span)> {
             match &pat.kind {
                 PatKind::Range(
@@ -2348,11 +2348,11 @@ impl<'tcx> LateLintPass<'tcx> for InvalidValue {
             Uninit,
         };
 
-        /// Information about why a type cannot be initialized this way.
-        /// Contains an error message and optionally a span to point at.
+        // Information about why a type cannot be initialized this way.
+        // Contains an error message and optionally a span to point at.
         type InitError = (String, Option<Span>);
 
-        /// Test if this constant is all-0.
+        // Test if this constant is all-0.
         fn is_zero(expr: &hir::Expr<'_>) -> bool {
             use hir::ExprKind::*;
             use rustc_ast::LitKind::*;
@@ -2369,7 +2369,7 @@ impl<'tcx> LateLintPass<'tcx> for InvalidValue {
             }
         }
 
-        /// Determine if this expression is a "dangerous initialization".
+        // Determine if this expression is a "dangerous initialization".
         fn is_dangerous_init(cx: &LateContext<'_>, expr: &hir::Expr<'_>) -> Option<InitKind> {
             if let hir::ExprKind::Call(ref path_expr, ref args) = expr.kind {
                 // Find calls to `mem::{uninitialized,zeroed}` methods.
@@ -2409,16 +2409,16 @@ impl<'tcx> LateLintPass<'tcx> for InvalidValue {
             None
         }
 
-        /// Test if this enum has several actually "existing" variants.
-        /// Zero-sized uninhabited variants do not always have a tag assigned and thus do not "exist".
+        // Test if this enum has several actually "existing" variants.
+        // Zero-sized uninhabited variants do not always have a tag assigned and thus do not "exist".
         fn is_multi_variant(adt: &ty::AdtDef) -> bool {
             // As an approximation, we only count dataless variants. Those are definitely inhabited.
             let existing_variants = adt.variants.iter().filter(|v| v.fields.is_empty()).count();
             existing_variants > 1
         }
 
-        /// Return `Some` only if we are sure this type does *not*
-        /// allow zero initialization.
+        // Return `Some` only if we are sure this type does *not*
+        // allow zero initialization.
         fn ty_find_init_error<'tcx>(
             tcx: TyCtxt<'tcx>,
             ty: Ty<'tcx>,
diff --git a/compiler/rustc_middle/src/mir/query.rs b/compiler/rustc_middle/src/mir/query.rs
index 6022194342d02..27d5f300f4349 100644
--- a/compiler/rustc_middle/src/mir/query.rs
+++ b/compiler/rustc_middle/src/mir/query.rs
@@ -167,7 +167,7 @@ pub struct GeneratorLayout<'tcx> {
 
 impl Debug for GeneratorLayout<'_> {
     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
-        /// Prints an iterator of (key, value) tuples as a map.
+        // Prints an iterator of (key, value) tuples as a map.
         struct MapPrinter<'a, K, V>(Cell<Option<Box<dyn Iterator<Item = (K, V)> + 'a>>>);
         impl<'a, K, V> MapPrinter<'a, K, V> {
             fn new(iter: impl Iterator<Item = (K, V)> + 'a) -> Self {
@@ -180,7 +180,7 @@ impl Debug for GeneratorLayout<'_> {
             }
         }
 
-        /// Prints the generator variant name.
+        // Prints the generator variant name.
         struct GenVariantPrinter(VariantIdx);
         impl From<VariantIdx> for GenVariantPrinter {
             fn from(idx: VariantIdx) -> Self {
@@ -198,7 +198,7 @@ impl Debug for GeneratorLayout<'_> {
             }
         }
 
-        /// Forces its contents to print in regular mode instead of alternate mode.
+        // Forces its contents to print in regular mode instead of alternate mode.
         struct OneLinePrinter<T>(T);
         impl<T: Debug> Debug for OneLinePrinter<T> {
             fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
diff --git a/compiler/rustc_mir/src/interpret/operand.rs b/compiler/rustc_mir/src/interpret/operand.rs
index 3c68b1c8355d5..8723b5c15ee59 100644
--- a/compiler/rustc_mir/src/interpret/operand.rs
+++ b/compiler/rustc_mir/src/interpret/operand.rs
@@ -94,7 +94,7 @@ pub struct ImmTy<'tcx, Tag = ()> {
 
 impl<Tag: Copy> std::fmt::Display for ImmTy<'tcx, Tag> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        /// Helper function for printing a scalar to a FmtPrinter
+        // Helper function for printing a scalar to a FmtPrinter
         fn p<'a, 'tcx, F: std::fmt::Write, Tag>(
             cx: FmtPrinter<'a, 'tcx, F>,
             s: ScalarMaybeUninit<Tag>,
diff --git a/compiler/rustc_mir/src/transform/simplify_try.rs b/compiler/rustc_mir/src/transform/simplify_try.rs
index 27bb1def726e1..8ff12d50928e5 100644
--- a/compiler/rustc_mir/src/transform/simplify_try.rs
+++ b/compiler/rustc_mir/src/transform/simplify_try.rs
@@ -106,8 +106,8 @@ fn get_arm_identity_info<'a, 'tcx>(
         matches!(stmt.kind, StatementKind::StorageLive(_) | StatementKind::StorageDead(_))
     }
 
-    /// Eats consecutive Statements which match `test`, performing the specified `action` for each.
-    /// The iterator `stmt_iter` is not advanced if none were matched.
+    // Eats consecutive Statements which match `test`, performing the specified `action` for each.
+    // The iterator `stmt_iter` is not advanced if none were matched.
     fn try_eat<'a, 'tcx>(
         stmt_iter: &mut StmtIter<'a, 'tcx>,
         test: impl Fn(&'a Statement<'tcx>) -> bool,
@@ -120,8 +120,8 @@ fn get_arm_identity_info<'a, 'tcx>(
         }
     }
 
-    /// Eats consecutive `StorageLive` and `StorageDead` Statements.
-    /// The iterator `stmt_iter` is not advanced if none were found.
+    // Eats consecutive `StorageLive` and `StorageDead` Statements.
+    // The iterator `stmt_iter` is not advanced if none were found.
     fn try_eat_storage_stmts<'a, 'tcx>(
         stmt_iter: &mut StmtIter<'a, 'tcx>,
         storage_live_stmts: &mut Vec<(usize, Local)>,
@@ -145,7 +145,7 @@ fn get_arm_identity_info<'a, 'tcx>(
         }
     }
 
-    /// Eats consecutive `Assign` Statements.
+    // Eats consecutive `Assign` Statements.
     // The iterator `stmt_iter` is not advanced if none were found.
     fn try_eat_assign_tmp_stmts<'a, 'tcx>(
         stmt_iter: &mut StmtIter<'a, 'tcx>,
diff --git a/compiler/rustc_mir_build/src/thir/pattern/_match.rs b/compiler/rustc_mir_build/src/thir/pattern/_match.rs
index 0449e14983150..a5d5c39e67186 100644
--- a/compiler/rustc_mir_build/src/thir/pattern/_match.rs
+++ b/compiler/rustc_mir_build/src/thir/pattern/_match.rs
@@ -2260,9 +2260,9 @@ fn split_grouped_constructors<'p, 'tcx>(
                     continue;
                 }
 
-                /// Represents a border between 2 integers. Because the intervals spanning borders
-                /// must be able to cover every integer, we need to be able to represent
-                /// 2^128 + 1 such borders.
+                // Represents a border between 2 integers. Because the intervals spanning borders
+                // must be able to cover every integer, we need to be able to represent
+                // 2^128 + 1 such borders.
                 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
                 enum Border {
                     JustBefore(u128),
diff --git a/compiler/rustc_parse/src/parser/nonterminal.rs b/compiler/rustc_parse/src/parser/nonterminal.rs
index 98fb1c8292510..29e7a44a8e58c 100644
--- a/compiler/rustc_parse/src/parser/nonterminal.rs
+++ b/compiler/rustc_parse/src/parser/nonterminal.rs
@@ -12,7 +12,7 @@ impl<'a> Parser<'a> {
     /// Returning `false` is a *stability guarantee* that such a matcher will *never* begin with that
     /// token. Be conservative (return true) if not sure.
     pub fn nonterminal_may_begin_with(kind: NonterminalKind, token: &Token) -> bool {
-        /// Checks whether the non-terminal may contain a single (non-keyword) identifier.
+        // Checks whether the non-terminal may contain a single (non-keyword) identifier.
         fn may_be_ident(nt: &token::Nonterminal) -> bool {
             match *nt {
                 token::NtItem(_) | token::NtBlock(_) | token::NtVis(_) | token::NtLifetime(_) => {
diff --git a/compiler/rustc_passes/src/region.rs b/compiler/rustc_passes/src/region.rs
index 1af79abe4b911..d65015bd8d1ca 100644
--- a/compiler/rustc_passes/src/region.rs
+++ b/compiler/rustc_passes/src/region.rs
@@ -509,17 +509,17 @@ fn resolve_local<'tcx>(
         visitor.visit_pat(pat);
     }
 
-    /// Returns `true` if `pat` match the `P&` non-terminal.
-    ///
-    /// ```text
-    ///     P& = ref X
-    ///        | StructName { ..., P&, ... }
-    ///        | VariantName(..., P&, ...)
-    ///        | [ ..., P&, ... ]
-    ///        | ( ..., P&, ... )
-    ///        | ... "|" P& "|" ...
-    ///        | box P&
-    /// ```
+    // Returns `true` if `pat` match the `P&` non-terminal.
+    //
+    // ```text
+    //     P& = ref X
+    //        | StructName { ..., P&, ... }
+    //        | VariantName(..., P&, ...)
+    //        | [ ..., P&, ... ]
+    //        | ( ..., P&, ... )
+    //        | ... "|" P& "|" ...
+    //        | box P&
+    // ```
     fn is_binding_pat(pat: &hir::Pat<'_>) -> bool {
         // Note that the code below looks for *explicit* refs only, that is, it won't
         // know about *implicit* refs as introduced in #42640.
@@ -576,18 +576,18 @@ fn resolve_local<'tcx>(
         }
     }
 
-    /// If `expr` matches the `E&` grammar, then records an extended rvalue scope as appropriate:
-    ///
-    /// ```text
-    ///     E& = & ET
-    ///        | StructName { ..., f: E&, ... }
-    ///        | [ ..., E&, ... ]
-    ///        | ( ..., E&, ... )
-    ///        | {...; E&}
-    ///        | box E&
-    ///        | E& as ...
-    ///        | ( E& )
-    /// ```
+    // If `expr` matches the `E&` grammar, then records an extended rvalue scope as appropriate:
+    //
+    // ```text
+    //     E& = & ET
+    //        | StructName { ..., f: E&, ... }
+    //        | [ ..., E&, ... ]
+    //        | ( ..., E&, ... )
+    //        | {...; E&}
+    //        | box E&
+    //        | E& as ...
+    //        | ( E& )
+    // ```
     fn record_rvalue_scope_if_borrow_expr<'tcx>(
         visitor: &mut RegionResolutionVisitor<'tcx>,
         expr: &hir::Expr<'_>,
@@ -620,23 +620,23 @@ fn resolve_local<'tcx>(
         }
     }
 
-    /// Applied to an expression `expr` if `expr` -- or something owned or partially owned by
-    /// `expr` -- is going to be indirectly referenced by a variable in a let statement. In that
-    /// case, the "temporary lifetime" or `expr` is extended to be the block enclosing the `let`
-    /// statement.
-    ///
-    /// More formally, if `expr` matches the grammar `ET`, record the rvalue scope of the matching
-    /// `<rvalue>` as `blk_id`:
-    ///
-    /// ```text
-    ///     ET = *ET
-    ///        | ET[...]
-    ///        | ET.f
-    ///        | (ET)
-    ///        | <rvalue>
-    /// ```
-    ///
-    /// Note: ET is intended to match "rvalues or places based on rvalues".
+    // Applied to an expression `expr` if `expr` -- or something owned or partially owned by
+    // `expr` -- is going to be indirectly referenced by a variable in a let statement. In that
+    // case, the "temporary lifetime" or `expr` is extended to be the block enclosing the `let`
+    // statement.
+    //
+    // More formally, if `expr` matches the grammar `ET`, record the rvalue scope of the matching
+    // `<rvalue>` as `blk_id`:
+    //
+    // ```text
+    //     ET = *ET
+    //        | ET[...]
+    //        | ET.f
+    //        | (ET)
+    //        | <rvalue>
+    // ```
+    //
+    // Note: ET is intended to match "rvalues or places based on rvalues".
     fn record_rvalue_scope<'tcx>(
         visitor: &mut RegionResolutionVisitor<'tcx>,
         expr: &hir::Expr<'_>,
diff --git a/compiler/rustc_resolve/src/imports.rs b/compiler/rustc_resolve/src/imports.rs
index adff4542b0ff8..a2547c0c9a40f 100644
--- a/compiler/rustc_resolve/src/imports.rs
+++ b/compiler/rustc_resolve/src/imports.rs
@@ -730,7 +730,7 @@ impl<'a, 'b> ImportResolver<'a, 'b> {
         errors: Vec<(String, UnresolvedImportError)>,
         span: Option<MultiSpan>,
     ) {
-        /// Upper limit on the number of `span_label` messages.
+        // Upper limit on the number of `span_label` messages.
         const MAX_LABEL_COUNT: usize = 10;
 
         let (span, msg) = if errors.is_empty() {
diff --git a/compiler/rustc_trait_selection/src/traits/error_reporting/mod.rs b/compiler/rustc_trait_selection/src/traits/error_reporting/mod.rs
index f8bd3ab96e254..3d60b957e3ebe 100644
--- a/compiler/rustc_trait_selection/src/traits/error_reporting/mod.rs
+++ b/compiler/rustc_trait_selection/src/traits/error_reporting/mod.rs
@@ -1242,8 +1242,8 @@ impl<'a, 'tcx> InferCtxtPrivExt<'tcx> for InferCtxt<'a, 'tcx> {
     }
 
     fn fuzzy_match_tys(&self, a: Ty<'tcx>, b: Ty<'tcx>) -> bool {
-        /// returns the fuzzy category of a given type, or None
-        /// if the type can be equated to any type.
+        // returns the fuzzy category of a given type, or None
+        // if the type can be equated to any type.
         fn type_category(t: Ty<'_>) -> Option<u32> {
             match t.kind() {
                 ty::Bool => Some(0),
diff --git a/library/alloc/src/collections/vec_deque.rs b/library/alloc/src/collections/vec_deque.rs
index 22b02a4f849b6..b467f62aaa621 100644
--- a/library/alloc/src/collections/vec_deque.rs
+++ b/library/alloc/src/collections/vec_deque.rs
@@ -154,8 +154,8 @@ impl<T: Clone> Clone for VecDeque<T> {
 #[stable(feature = "rust1", since = "1.0.0")]
 unsafe impl<#[may_dangle] T> Drop for VecDeque<T> {
     fn drop(&mut self) {
-        /// Runs the destructor for all items in the slice when it gets dropped (normally or
-        /// during unwinding).
+        // Runs the destructor for all items in the slice when it gets dropped (normally or
+        // during unwinding).
         struct Dropper<'a, T>(&'a mut [T]);
 
         impl<'a, T> Drop for Dropper<'a, T> {
@@ -901,8 +901,8 @@ impl<T> VecDeque<T> {
     /// ```
     #[stable(feature = "deque_extras", since = "1.16.0")]
     pub fn truncate(&mut self, len: usize) {
-        /// Runs the destructor for all items in the slice when it gets dropped (normally or
-        /// during unwinding).
+        // Runs the destructor for all items in the slice when it gets dropped (normally or
+        // during unwinding).
         struct Dropper<'a, T>(&'a mut [T]);
 
         impl<'a, T> Drop for Dropper<'a, T> {
diff --git a/library/alloc/src/vec.rs b/library/alloc/src/vec.rs
index 5b3604db563c6..9517f73f519d3 100644
--- a/library/alloc/src/vec.rs
+++ b/library/alloc/src/vec.rs
@@ -3144,8 +3144,8 @@ impl<T> DoubleEndedIterator for Drain<'_, T> {
 #[stable(feature = "drain", since = "1.6.0")]
 impl<T> Drop for Drain<'_, T> {
     fn drop(&mut self) {
-        /// Continues dropping the remaining elements in the `Drain`, then moves back the
-        /// un-`Drain`ed elements to restore the original `Vec`.
+        // Continues dropping the remaining elements in the `Drain`, then moves back the
+        // un-`Drain`ed elements to restore the original `Vec`.
         struct DropGuard<'r, 'a, T>(&'r mut Drain<'a, T>);
 
         impl<'r, 'a, T> Drop for DropGuard<'r, 'a, T> {
diff --git a/library/alloc/tests/vec.rs b/library/alloc/tests/vec.rs
index 771a293b8e5d4..303229a66a4af 100644
--- a/library/alloc/tests/vec.rs
+++ b/library/alloc/tests/vec.rs
@@ -1541,8 +1541,8 @@ fn test_try_reserve_exact() {
 
 #[test]
 fn test_stable_pointers() {
-    /// Pull an element from the iterator, then drop it.
-    /// Useful to cover both the `next` and `drop` paths of an iterator.
+    // Pull an element from the iterator, then drop it.
+    // Useful to cover both the `next` and `drop` paths of an iterator.
     fn next_then_drop<I: Iterator>(mut i: I) {
         i.next().unwrap();
         drop(i);
diff --git a/library/core/src/intrinsics.rs b/library/core/src/intrinsics.rs
index dbc7921a62a67..a22f51956fc61 100644
--- a/library/core/src/intrinsics.rs
+++ b/library/core/src/intrinsics.rs
@@ -1800,7 +1800,7 @@ pub(crate) fn is_nonoverlapping<T>(src: *const T, dst: *const T, count: usize) -
 /// ```
 /// use std::ptr;
 ///
-/// /// Moves all the elements of `src` into `dst`, leaving `src` empty.
+/// // Moves all the elements of `src` into `dst`, leaving `src` empty.
 /// fn append<T>(dst: &mut Vec<T>, src: &mut Vec<T>) {
 ///     let src_len = src.len();
 ///     let dst_len = dst.len();
@@ -1907,6 +1907,7 @@ pub unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize) {
 /// /// * `ptr` must be valid for reads of `elts` contiguous elements of type `T`.
 /// /// * Those elements must not be used after calling this function unless `T: Copy`.
 /// # #[allow(dead_code)]
+/// # #[allow(unused_doc_comments)]
 /// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
 ///     let mut dst = Vec::with_capacity(elts);
 ///
diff --git a/library/core/src/iter/mod.rs b/library/core/src/iter/mod.rs
index 59f333e888b88..0199bdbb071fe 100644
--- a/library/core/src/iter/mod.rs
+++ b/library/core/src/iter/mod.rs
@@ -80,7 +80,7 @@
 //! ```
 //! // First, the struct:
 //!
-//! /// An iterator which counts from one to five
+//! // An iterator which counts from one to five
 //! struct Counter {
 //!     count: usize,
 //! }
diff --git a/library/core/src/mem/maybe_uninit.rs b/library/core/src/mem/maybe_uninit.rs
index 862c452a43480..e1b6961017dc7 100644
--- a/library/core/src/mem/maybe_uninit.rs
+++ b/library/core/src/mem/maybe_uninit.rs
@@ -302,7 +302,7 @@ impl<T> MaybeUninit<T> {
     ///     fn read_into_buffer(ptr: *mut u8, max_len: usize) -> usize;
     /// }
     ///
-    /// /// Returns a (possibly smaller) slice of data that was actually read
+    /// // Returns a (possibly smaller) slice of data that was actually read
     /// fn read(buf: &mut [MaybeUninit<u8>]) -> &[u8] {
     ///     unsafe {
     ///         let len = read_into_buffer(buf.as_mut_ptr() as *mut u8, buf.len());
diff --git a/library/core/src/panic.rs b/library/core/src/panic.rs
index 34a974b827158..a168989b38bb3 100644
--- a/library/core/src/panic.rs
+++ b/library/core/src/panic.rs
@@ -191,13 +191,13 @@ impl<'a> Location<'a> {
     /// ```
     /// use core::panic::Location;
     ///
-    /// /// Returns the [`Location`] at which it is called.
+    /// // Returns the [`Location`] at which it is called.
     /// #[track_caller]
     /// fn get_caller_location() -> &'static Location<'static> {
     ///     Location::caller()
     /// }
     ///
-    /// /// Returns a [`Location`] from within this function's definition.
+    /// // Returns a [`Location`] from within this function's definition.
     /// fn get_just_one_location() -> &'static Location<'static> {
     ///     get_caller_location()
     /// }
diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs
index bca3be56ba5f5..2d49d08b6c32d 100644
--- a/library/core/src/ptr/mod.rs
+++ b/library/core/src/ptr/mod.rs
@@ -1145,24 +1145,24 @@ pub(crate) unsafe fn align_offset<T: Sized>(p: *const T, a: usize) -> usize {
     // 1, where the method versions of these operations are not inlined.
     use intrinsics::{unchecked_shl, unchecked_shr, unchecked_sub, wrapping_mul, wrapping_sub};
 
-    /// Calculate multiplicative modular inverse of `x` modulo `m`.
-    ///
-    /// This implementation is tailored for `align_offset` and has following preconditions:
-    ///
-    /// * `m` is a power-of-two;
-    /// * `x < m`; (if `x ≥ m`, pass in `x % m` instead)
-    ///
-    /// Implementation of this function shall not panic. Ever.
+    // Calculate multiplicative modular inverse of `x` modulo `m`.
+    //
+    // This implementation is tailored for `align_offset` and has following preconditions:
+    //
+    // * `m` is a power-of-two;
+    // * `x < m`; (if `x ≥ m`, pass in `x % m` instead)
+    //
+    // Implementation of this function shall not panic. Ever.
     #[inline]
     unsafe fn mod_inv(x: usize, m: usize) -> usize {
-        /// Multiplicative modular inverse table modulo 2⁴ = 16.
-        ///
-        /// Note, that this table does not contain values where inverse does not exist (i.e., for
-        /// `0⁻¹ mod 16`, `2⁻¹ mod 16`, etc.)
+        // Multiplicative modular inverse table modulo 2⁴ = 16.
+        //
+        // Note, that this table does not contain values where inverse does not exist (i.e., for
+        // `0⁻¹ mod 16`, `2⁻¹ mod 16`, etc.)
         const INV_TABLE_MOD_16: [u8; 8] = [1, 11, 13, 7, 9, 3, 5, 15];
-        /// Modulo for which the `INV_TABLE_MOD_16` is intended.
+        // Modulo for which the `INV_TABLE_MOD_16` is intended.
         const INV_TABLE_MOD: usize = 16;
-        /// INV_TABLE_MOD²
+        // INV_TABLE_MOD²
         const INV_TABLE_MOD_SQUARED: usize = INV_TABLE_MOD * INV_TABLE_MOD;
 
         let table_inverse = INV_TABLE_MOD_16[(x & (INV_TABLE_MOD - 1)) >> 1] as usize;
diff --git a/library/core/src/time.rs b/library/core/src/time.rs
index 6dc542dee58e6..cdc9f21475817 100644
--- a/library/core/src/time.rs
+++ b/library/core/src/time.rs
@@ -987,16 +987,16 @@ impl<'a> Sum<&'a Duration> for Duration {
 #[stable(feature = "duration_debug_impl", since = "1.27.0")]
 impl fmt::Debug for Duration {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        /// Formats a floating point number in decimal notation.
-        ///
-        /// The number is given as the `integer_part` and a fractional part.
-        /// The value of the fractional part is `fractional_part / divisor`. So
-        /// `integer_part` = 3, `fractional_part` = 12 and `divisor` = 100
-        /// represents the number `3.012`. Trailing zeros are omitted.
-        ///
-        /// `divisor` must not be above 100_000_000. It also should be a power
-        /// of 10, everything else doesn't make sense. `fractional_part` has
-        /// to be less than `10 * divisor`!
+        // Formats a floating point number in decimal notation.
+        //
+        // The number is given as the `integer_part` and a fractional part.
+        // The value of the fractional part is `fractional_part / divisor`. So
+        // `integer_part` = 3, `fractional_part` = 12 and `divisor` = 100
+        // represents the number `3.012`. Trailing zeros are omitted.
+        //
+        // `divisor` must not be above 100_000_000. It also should be a power
+        // of 10, everything else doesn't make sense. `fractional_part` has
+        // to be less than `10 * divisor`!
         fn fmt_decimal(
             f: &mut fmt::Formatter<'_>,
             mut integer_part: u64,
diff --git a/library/proc_macro/src/bridge/scoped_cell.rs b/library/proc_macro/src/bridge/scoped_cell.rs
index e7c32b10384d4..a7a8dfb464bfa 100644
--- a/library/proc_macro/src/bridge/scoped_cell.rs
+++ b/library/proc_macro/src/bridge/scoped_cell.rs
@@ -50,9 +50,9 @@ impl<T: LambdaL> ScopedCell<T> {
         replacement: <T as ApplyL<'a>>::Out,
         f: impl for<'b, 'c> FnOnce(RefMutL<'b, 'c, T>) -> R,
     ) -> R {
-        /// Wrapper that ensures that the cell always gets filled
-        /// (with the original state, optionally changed by `f`),
-        /// even if `f` had panicked.
+        // Wrapper that ensures that the cell always gets filled
+        // (with the original state, optionally changed by `f`),
+        // even if `f` had panicked.
         struct PutBackOnDrop<'a, T: LambdaL> {
             cell: &'a ScopedCell<T>,
             value: Option<<T as ApplyL<'static>>::Out>,
diff --git a/library/std/src/io/buffered/bufwriter.rs b/library/std/src/io/buffered/bufwriter.rs
index 8ce795a05ed36..c041a4b725533 100644
--- a/library/std/src/io/buffered/bufwriter.rs
+++ b/library/std/src/io/buffered/bufwriter.rs
@@ -115,9 +115,9 @@ impl<W: Write> BufWriter<W> {
     /// `write`), any 0-length writes from `inner` must be reported as i/o
     /// errors from this method.
     pub(super) fn flush_buf(&mut self) -> io::Result<()> {
-        /// Helper struct to ensure the buffer is updated after all the writes
-        /// are complete. It tracks the number of written bytes and drains them
-        /// all from the front of the buffer when dropped.
+        // Helper struct to ensure the buffer is updated after all the writes
+        // are complete. It tracks the number of written bytes and drains them
+        // all from the front of the buffer when dropped.
         struct BufGuard<'a> {
             buffer: &'a mut Vec<u8>,
             written: usize,
diff --git a/library/std/src/keyword_docs.rs b/library/std/src/keyword_docs.rs
index 9b704ee9ecab2..da65a131a1097 100644
--- a/library/std/src/keyword_docs.rs
+++ b/library/std/src/keyword_docs.rs
@@ -1945,11 +1945,11 @@ mod type_keyword {}
 ///
 /// ```rust
 /// # #![allow(dead_code)]
-/// /// Dereference the given pointer.
-/// ///
-/// /// # Safety
-/// ///
-/// /// `ptr` must be aligned and must not be dangling.
+/// // Dereference the given pointer.
+/// //
+/// // # Safety
+/// //
+/// // `ptr` must be aligned and must not be dangling.
 /// unsafe fn deref_unchecked(ptr: *const i32) -> i32 {
 ///     *ptr
 /// }
@@ -1967,8 +1967,8 @@ mod type_keyword {}
 /// this behaviour in the standard library.
 ///
 /// ```rust
-/// /// Implementors of this trait must guarantee an element is always
-/// /// accessible with index 3.
+/// // Implementors of this trait must guarantee an element is always
+/// // accessible with index 3.
 /// unsafe trait ThreeIndexable<T> {
 ///     /// Returns a reference to the element with index 3 in `&self`.
 ///     fn three(&self) -> &T;
diff --git a/library/std/src/net/ip.rs b/library/std/src/net/ip.rs
index bb3ece4c2739f..35c7e19003185 100644
--- a/library/std/src/net/ip.rs
+++ b/library/std/src/net/ip.rs
@@ -1601,7 +1601,7 @@ impl fmt::Display for Ipv6Addr {
                     longest
                 };
 
-                /// Write a colon-separated part of the address
+                // Write a colon-separated part of the address
                 #[inline]
                 fn fmt_subslice(f: &mut fmt::Formatter<'_>, chunk: &[u16]) -> fmt::Result {
                     if let Some(first) = chunk.first() {
diff --git a/library/std/src/net/parser.rs b/library/std/src/net/parser.rs
index e8b89626fbde1..3ac8724e6da61 100644
--- a/library/std/src/net/parser.rs
+++ b/library/std/src/net/parser.rs
@@ -141,11 +141,11 @@ impl<'a> Parser<'a> {
 
     /// Read an IPV6 Address
     fn read_ipv6_addr(&mut self) -> Option<Ipv6Addr> {
-        /// Read a chunk of an ipv6 address into `groups`. Returns the number
-        /// of groups read, along with a bool indicating if an embedded
-        /// trailing ipv4 address was read. Specifically, read a series of
-        /// colon-separated ipv6 groups (0x0000 - 0xFFFF), with an optional
-        /// trailing embedded ipv4 address.
+        // Read a chunk of an ipv6 address into `groups`. Returns the number
+        // of groups read, along with a bool indicating if an embedded
+        // trailing ipv4 address was read. Specifically, read a series of
+        // colon-separated ipv6 groups (0x0000 - 0xFFFF), with an optional
+        // trailing embedded ipv4 address.
         fn read_groups(p: &mut Parser<'_>, groups: &mut [u16]) -> (usize, bool) {
             let limit = groups.len();
 
diff --git a/src/librustdoc/clean/types.rs b/src/librustdoc/clean/types.rs
index 32b3f69ecd4f0..23dada4d4bf7c 100644
--- a/src/librustdoc/clean/types.rs
+++ b/src/librustdoc/clean/types.rs
@@ -1360,16 +1360,16 @@ impl PrimitiveType {
         CELL.get_or_init(move || {
             use self::PrimitiveType::*;
 
-            /// A macro to create a FxHashMap.
-            ///
-            /// Example:
-            ///
-            /// ```
-            /// let letters = map!{"a" => "b", "c" => "d"};
-            /// ```
-            ///
-            /// Trailing commas are allowed.
-            /// Commas between elements are required (even if the expression is a block).
+            // A macro to create a FxHashMap.
+            //
+            // Example:
+            //
+            // ```
+            // let letters = map!{"a" => "b", "c" => "d"};
+            // ```
+            //
+            // Trailing commas are allowed.
+            // Commas between elements are required (even if the expression is a block).
             macro_rules! map {
                 ($( $key: expr => $val: expr ),* $(,)*) => {{
                     let mut map = ::rustc_data_structures::fx::FxHashMap::default();
diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs
index 1726093c6facb..ab53cca132143 100644
--- a/src/librustdoc/html/render/mod.rs
+++ b/src/librustdoc/html/render/mod.rs
@@ -1993,7 +1993,7 @@ fn document_non_exhaustive(w: &mut Buffer, item: &clean::Item) {
 
 /// Compare two strings treating multi-digit numbers as single units (i.e. natural sort order).
 pub fn compare_names(mut lhs: &str, mut rhs: &str) -> Ordering {
-    /// Takes a non-numeric and a numeric part from the given &str.
+    // Takes a non-numeric and a numeric part from the given &str.
     fn take_parts<'a>(s: &mut &'a str) -> (&'a str, &'a str) {
         let i = s.find(|c: char| c.is_ascii_digit());
         let (a, b) = s.split_at(i.unwrap_or(s.len()));