Avoid comments that describe multiple use items.

There are some comments describing multiple subsequent `use` items. When
the big `use` reformatting happens some of these `use` items will be
reordered, possibly moving them away from the comment. With this
additional level of formatting it's not really feasible to have comments
of this type. This commit removes them in various ways:

- merging separate `use` items when appropriate;

- inserting blank lines between the comment and the first `use` item;

- outright deletion (for comments that are relatively low-value);

- adding a separate "top-level" comment.

We also entirely skip formatting for four library files that contain
nothing but `pub use` re-exports, where reordering would be painful.

Author: nnethercote

Diff for: core/src/char/mod.rs

@@ -24,19 +24,17 @@ mod convert;
 mod decode;
 mod methods;
 
-// stable re-exports
 #[stable(feature = "try_from", since = "1.34.0")]
 pub use self::convert::CharTryFromError;
 #[stable(feature = "char_from_str", since = "1.20.0")]
 pub use self::convert::ParseCharError;
 #[stable(feature = "decode_utf16", since = "1.9.0")]
 pub use self::decode::{DecodeUtf16, DecodeUtf16Error};
 
-// perma-unstable re-exports
 #[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")]
-pub use self::methods::encode_utf16_raw;
+pub use self::methods::encode_utf16_raw; // perma-unstable
 #[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")]
-pub use self::methods::encode_utf8_raw;
+pub use self::methods::encode_utf8_raw; // perma-unstable
 
 use crate::ascii;
 use crate::error::Error;

Diff for: core/src/prelude/common.rs

@@ -2,6 +2,9 @@
 //!
 //! See the [module-level documentation](super) for more.
 
+// No formatting: this file is nothing but re-exports, and their order is worth preserving.
+#![cfg_attr(rustfmt, rustfmt::skip)]
+
 // Re-exported core operators
 #[stable(feature = "core_prelude", since = "1.4.0")]
 #[doc(no_inline)]

Diff for: core/src/prelude/mod.rs

@@ -4,6 +4,9 @@
 //! This module is imported by default when `#![no_std]` is used in the same
 //! manner as the standard library's prelude.
 
+// No formatting: this file is nothing but re-exports, and their order is worth preserving.
+#![cfg_attr(rustfmt, rustfmt::skip)]
+
 #![stable(feature = "core_prelude", since = "1.4.0")]
 
 mod common;

Diff for: core/src/ptr/mod.rs

@@ -1809,10 +1809,9 @@ pub(crate) const unsafe fn align_offset<T: Sized>(p: *const T, a: usize) -> usiz
     // FIXME(#75598): Direct use of these intrinsics improves codegen significantly at opt-level <=
     // 1, where the method versions of these operations are not inlined.
     use intrinsics::{
-        assume, cttz_nonzero, exact_div, mul_with_overflow, unchecked_rem, unchecked_sub,
-        wrapping_add, wrapping_mul, wrapping_sub,
+        assume, cttz_nonzero, exact_div, mul_with_overflow, unchecked_rem, unchecked_shl,
+        unchecked_shr, unchecked_sub, wrapping_add, wrapping_mul, wrapping_sub,
     };
-    use intrinsics::{unchecked_shl, unchecked_shr};
 
     /// Calculate multiplicative modular inverse of `x` modulo `m`.
     ///

Diff for: core/src/unicode/mod.rs

@@ -1,6 +1,19 @@
 #![unstable(feature = "unicode_internals", issue = "none")]
 #![allow(missing_docs)]
 
+// The `pub use` ones are for use in alloc, and are not re-exported in std.
+
+pub(crate) use unicode_data::alphabetic::lookup as Alphabetic;
+pub use unicode_data::case_ignorable::lookup as Case_Ignorable;
+pub use unicode_data::cased::lookup as Cased;
+pub(crate) use unicode_data::cc::lookup as Cc;
+pub use unicode_data::conversions;
+pub(crate) use unicode_data::grapheme_extend::lookup as Grapheme_Extend;
+pub(crate) use unicode_data::lowercase::lookup as Lowercase;
+pub(crate) use unicode_data::n::lookup as N;
+pub(crate) use unicode_data::uppercase::lookup as Uppercase;
+pub(crate) use unicode_data::white_space::lookup as White_Space;
+
 pub(crate) mod printable;
 mod unicode_data;
 
@@ -16,16 +29,3 @@ mod unicode_data;
 /// [Unicode 11.0 or later, Section 3.1 Versions of the Unicode Standard](https://www.unicode.org/versions/Unicode11.0.0/ch03.pdf#page=4).
 #[stable(feature = "unicode_version", since = "1.45.0")]
 pub const UNICODE_VERSION: (u8, u8, u8) = unicode_data::UNICODE_VERSION;
-
-// For use in alloc, not re-exported in std.
-pub use unicode_data::{
-    case_ignorable::lookup as Case_Ignorable, cased::lookup as Cased, conversions,
-};
-
-pub(crate) use unicode_data::alphabetic::lookup as Alphabetic;
-pub(crate) use unicode_data::cc::lookup as Cc;
-pub(crate) use unicode_data::grapheme_extend::lookup as Grapheme_Extend;
-pub(crate) use unicode_data::lowercase::lookup as Lowercase;
-pub(crate) use unicode_data::n::lookup as N;
-pub(crate) use unicode_data::uppercase::lookup as Uppercase;
-pub(crate) use unicode_data::white_space::lookup as White_Space;

Diff for: std/src/lib.rs

@@ -469,7 +469,6 @@ pub mod rt;
 // The Rust prelude
 pub mod prelude;
 
-// Public module declarations and re-exports
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use alloc_crate::borrow;
 #[stable(feature = "rust1", since = "1.0.0")]

Diff for: std/src/os/fortanix_sgx/mod.rs

@@ -28,7 +28,6 @@ pub mod usercalls {
         pub use crate::sys::abi::usercalls::raw::{do_usercall, Usercalls as UsercallNrs};
         pub use crate::sys::abi::usercalls::raw::{Register, RegisterArgument, ReturnValue};
 
-        // fortanix-sgx-abi re-exports
         pub use crate::sys::abi::usercalls::raw::Error;
         pub use crate::sys::abi::usercalls::raw::{
             ByteBuffer, Cancel, FifoDescriptor, Return, Usercall,

Diff for: std/src/prelude/common.rs

@@ -2,6 +2,9 @@
 //!
 //! See the [module-level documentation](super) for more.
 
+// No formatting: this file is nothing but re-exports, and their order is worth preserving.
+#![cfg_attr(rustfmt, rustfmt::skip)]
+
 // Re-exported core operators
 #[stable(feature = "rust1", since = "1.0.0")]
 #[doc(no_inline)]

Diff for: std/src/prelude/mod.rs

@@ -95,6 +95,9 @@
 //! [book-enums]: ../../book/ch06-01-defining-an-enum.html
 //! [book-iter]: ../../book/ch13-02-iterators.html
 
+// No formatting: this file is nothing but re-exports, and their order is worth preserving.
+#![cfg_attr(rustfmt, rustfmt::skip)]
+
 #![stable(feature = "rust1", since = "1.0.0")]
 
 mod common;

Diff for: std/src/rt.rs

@@ -16,7 +16,6 @@
 #![deny(unsafe_op_in_unsafe_fn)]
 #![allow(unused_macros)]
 
-// Re-export some of our utilities which are expected by other crates.
 pub use crate::panicking::{begin_panic, panic_count};
 pub use core::panicking::{panic_display, panic_fmt};
 

Diff for: std/src/sys/pal/wasi/mod.rs

@@ -39,12 +39,15 @@ pub mod time;
 #[deny(unsafe_op_in_unsafe_fn)]
 #[allow(unused)]
 mod common;
+
 pub use common::*;
 
 mod helpers;
-// These exports are listed individually to work around Rust's glob import
-// conflict rules. If we glob export `helpers` and `common` together, then
-// the compiler complains about conflicts.
+
+// The following exports are listed individually to work around Rust's glob
+// import conflict rules. If we glob export `helpers` and `common` together,
+// then the compiler complains about conflicts.
+
 pub use helpers::abort_internal;
 pub use helpers::decode_error_kind;
 use helpers::err2io;

Diff for: std/src/sys/pal/wasip2/mod.rs

@@ -41,13 +41,16 @@ pub mod time;
 #[deny(unsafe_op_in_unsafe_fn)]
 #[allow(unused)]
 mod common;
+
 pub use common::*;
 
 #[path = "../wasi/helpers.rs"]
 mod helpers;
-// These exports are listed individually to work around Rust's glob import
-// conflict rules. If we glob export `helpers` and `common` together, then
-// the compiler complains about conflicts.
+
+// The following exports are listed individually to work around Rust's glob
+// import conflict rules. If we glob export `helpers` and `common` together,
+// then the compiler complains about conflicts.
+
 pub use helpers::abort_internal;
 pub use helpers::decode_error_kind;
 use helpers::err2io;

Diff for: test/src/lib.rs

@@ -25,7 +25,6 @@
 #![feature(test)]
 #![allow(internal_features)]
 
-// Public reexports
 pub use self::bench::{black_box, Bencher};
 pub use self::console::run_tests_console;
 pub use self::options::{ColorConfig, Options, OutputFormat, RunIgnored, ShouldPanic};