Convert some module-level `//` and `///` comments to `//!`.

This makes their intent and expected location clearer. We see some
examples where these comments were not clearly separate from `use`
declarations, which made it hard to understand what the comment is
describing.

9 files changed, 32 insertions, 26 deletions

diff --git a/compiler/rustc_builtin_macros/src/test.rs b/compiler/rustc_builtin_macros/src/test.rs
index 8f96070d149..c0310a2f4b0 100644
--- a/compiler/rustc_builtin_macros/src/test.rs
+++ b/compiler/rustc_builtin_macros/src/test.rs
@@ -1,6 +1,7 @@
+//! The expansion from a test function to the appropriate test struct for libtest
+//! Ideally, this code would be in libtest but for efficiency and error messages it lives here.
+
 use crate::errors;
-/// The expansion from a test function to the appropriate test struct for libtest
-/// Ideally, this code would be in libtest but for efficiency and error messages it lives here.
 use crate::util::{check_builtin_macro_attribute, warn_on_duplicate_attribute};
 use rustc_ast::ptr::P;
 use rustc_ast::{self as ast, attr, GenericParamKind};
diff --git a/compiler/rustc_data_structures/src/base_n.rs b/compiler/rustc_data_structures/src/base_n.rs
index aed89fadc4c..80810df14d0 100644
--- a/compiler/rustc_data_structures/src/base_n.rs
+++ b/compiler/rustc_data_structures/src/base_n.rs
@@ -1,5 +1,6 @@
-/// Converts unsigned integers into a string representation with some base.
-/// Bases up to and including 36 can be used for case-insensitive things.
+//! Converts unsigned integers into a string representation with some base.
+//! Bases up to and including 36 can be used for case-insensitive things.
+
 use std::ascii;
 use std::fmt;
 
diff --git a/compiler/rustc_middle/src/mir/statement.rs b/compiler/rustc_middle/src/mir/statement.rs
index 4d9a931d697..ac3feb71a2b 100644
--- a/compiler/rustc_middle/src/mir/statement.rs
+++ b/compiler/rustc_middle/src/mir/statement.rs
@@ -1,4 +1,5 @@
-/// Functionality for statements, operands, places, and things that appear in them.
+//! Functionality for statements, operands, places, and things that appear in them.
+
 use super::{interpret::GlobalAlloc, *};
 
 ///////////////////////////////////////////////////////////////////////////
diff --git a/compiler/rustc_middle/src/mir/terminator.rs b/compiler/rustc_middle/src/mir/terminator.rs
index c8c12e205e1..ed592612358 100644
--- a/compiler/rustc_middle/src/mir/terminator.rs
+++ b/compiler/rustc_middle/src/mir/terminator.rs
@@ -1,4 +1,5 @@
-/// Functionality for terminators and helper types that appear in terminators.
+//! Functionality for terminators and helper types that appear in terminators.
+
 use rustc_hir::LangItem;
 use smallvec::{smallvec, SmallVec};
 
diff --git a/compiler/rustc_target/src/spec/targets/mips64_openwrt_linux_musl.rs b/compiler/rustc_target/src/spec/targets/mips64_openwrt_linux_musl.rs
index b8bdfc943de..9df7b2b670f 100644
--- a/compiler/rustc_target/src/spec/targets/mips64_openwrt_linux_musl.rs
+++ b/compiler/rustc_target/src/spec/targets/mips64_openwrt_linux_musl.rs
@@ -1,5 +1,5 @@
-/// A target tuple for OpenWrt MIPS64 targets
-///
+//! A target tuple for OpenWrt MIPS64 targets.
+
 use crate::abi::Endian;
 use crate::spec::{base, Target, TargetOptions};
 
diff --git a/library/alloc/src/boxed/thin.rs b/library/alloc/src/boxed/thin.rs
index 8b145b67bf1..e9bfecba160 100644
--- a/library/alloc/src/boxed/thin.rs
+++ b/library/alloc/src/boxed/thin.rs
@@ -1,6 +1,7 @@
-// Based on
-// https://github.com/matthieu-m/rfc2580/blob/b58d1d3cba0d4b5e859d3617ea2d0943aaa31329/examples/thin.rs
-// by matthieu-m
+//! Based on
+//! <https://github.com/matthieu-m/rfc2580/blob/b58d1d3cba0d4b5e859d3617ea2d0943aaa31329/examples/thin.rs>
+//! by matthieu-m
+
 use crate::alloc::{self, Layout, LayoutError};
 use core::error::Error;
 use core::fmt::{self, Debug, Display, Formatter};
diff --git a/library/portable-simd/crates/core_simd/examples/dot_product.rs b/library/portable-simd/crates/core_simd/examples/dot_product.rs
index f047010a65c..75d152ae7f0 100644
--- a/library/portable-simd/crates/core_simd/examples/dot_product.rs
+++ b/library/portable-simd/crates/core_simd/examples/dot_product.rs
@@ -1,6 +1,5 @@
-// Code taken from the `packed_simd` crate
-// Run this code with `cargo test --example dot_product`
-//use std::iter::zip;
+//! Code taken from the `packed_simd` crate.
+//! Run this code with `cargo test --example dot_product`.
 
 #![feature(array_chunks)]
 #![feature(slice_as_chunks)]
diff --git a/library/std/src/io/buffered/bufreader/buffer.rs b/library/std/src/io/buffered/bufreader/buffer.rs
index e9e29d60ca2..796137c0123 100644
--- a/library/std/src/io/buffered/bufreader/buffer.rs
+++ b/library/std/src/io/buffered/bufreader/buffer.rs
@@ -1,13 +1,14 @@
-///! An encapsulation of `BufReader`'s buffer management logic.
-///
-/// This module factors out the basic functionality of `BufReader` in order to protect two core
-/// invariants:
-/// * `filled` bytes of `buf` are always initialized
-/// * `pos` is always <= `filled`
-/// Since this module encapsulates the buffer management logic, we can ensure that the range
-/// `pos..filled` is always a valid index into the initialized region of the buffer. This means
-/// that user code which wants to do reads from a `BufReader` via `buffer` + `consume` can do so
-/// without encountering any runtime bounds checks.
+//! An encapsulation of `BufReader`'s buffer management logic.
+//!
+//! This module factors out the basic functionality of `BufReader` in order to protect two core
+//! invariants:
+//! * `filled` bytes of `buf` are always initialized
+//! * `pos` is always <= `filled`
+//! Since this module encapsulates the buffer management logic, we can ensure that the range
+//! `pos..filled` is always a valid index into the initialized region of the buffer. This means
+//! that user code which wants to do reads from a `BufReader` via `buffer` + `consume` can do so
+//! without encountering any runtime bounds checks.
+
 use crate::cmp;
 use crate::io::{self, BorrowedBuf, Read};
 use crate::mem::MaybeUninit;
diff --git a/library/std/src/sys/os_str/wtf8.rs b/library/std/src/sys/os_str/wtf8.rs
index dfff4dd4fb0..96690f8c44e 100644
--- a/library/std/src/sys/os_str/wtf8.rs
+++ b/library/std/src/sys/os_str/wtf8.rs
@@ -1,5 +1,6 @@
-/// The underlying OsString/OsStr implementation on Windows is a
-/// wrapper around the "WTF-8" encoding; see the `wtf8` module for more.
+//! The underlying OsString/OsStr implementation on Windows is a
+//! wrapper around the "WTF-8" encoding; see the `wtf8` module for more.
+
 use crate::borrow::Cow;
 use crate::collections::TryReserveError;
 use crate::fmt;