Clean up and add more comments to libstd/lib.rs

src/libstd/lib.rs

@@ -210,8 +210,27 @@
        test(no_crate_inject, attr(deny(warnings))),
        test(attr(allow(dead_code, deprecated, unused_variables, unused_mut))))]
 
+// Don't link to std. We are std.
+#![no_std]
+
+#![deny(missing_docs)]
+
+// Tell the compiler to link to either panic_abort or panic_unwind
 #![needs_panic_runtime]
 
+// Always use alloc_system during stage0 since jemalloc might be unavailable or
+// disabled (Issue #30592)
+#![cfg_attr(stage0, feature(alloc_system))]
+
+// Turn warnings into errors, but only after stage0, where it can be useful for
+// code to emit warnings during language transitions
+#![cfg_attr(not(stage0), deny(warnings))]
+
+// std may use features in a platform-specific way
+#![allow(unused_features)]
+
+// std is implemented with unstable features, many of which are internal
+// compiler details that will never be stable
 #![feature(alloc)]
 #![feature(allow_internal_unstable)]
 #![feature(asm)]
@@ -283,21 +302,13 @@
 #![feature(zero_one)]
 #![cfg_attr(test, feature(update_panic_count))]
 
-// Issue# 30592: Systematically use alloc_system during stage0 since jemalloc
-// might be unavailable or disabled
-#![cfg_attr(stage0, feature(alloc_system))]
-
-// Don't link to std. We are std.
-#![no_std]
-
-#![deny(missing_docs)]
-#![allow(unused_features)] // std may use features in a platform-specific way
-#![cfg_attr(not(stage0), deny(warnings))]
-
+// Explicitly import the prelude. The compiler uses this same unstable attribute
+// to import the prelude implicitly when building crates that depend on std.
 #[prelude_import]
 #[allow(unused)]
 use prelude::v1::*;
 
+// Access to Bencher, etc.
 #[cfg(test)] extern crate test;
 
 // We want to reexport a few macros from core but libcore has already been
@@ -325,11 +336,22 @@ extern crate alloc_system;
 // compiler-rt intrinsics
 extern crate compiler_builtins;
 
-// Make std testable by not duplicating lang items and other globals. See #2912
+// During testing, this crate is not actually the "real" std library, but rather
+// it links to the real std library, which was compiled from this same source
+// code. So any lang items std defines are conditionally excluded (or else they
+// wolud generate duplicate lang item errors), and any globals it defines are
+// _not_ the globals used by "real" std. So this import, defined only during
+// testing gives test-std access to real-std lang items and globals. See #2912
 #[cfg(test)] extern crate std as realstd;
 
-// NB: These reexports are in the order they should be listed in rustdoc
+// The standard macros that are not built-in to the compiler.
+#[macro_use]
+mod macros;
+
+// The Rust prelude
+pub mod prelude;
 
+// Public module declarations and reexports
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::any;
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -362,48 +384,6 @@ pub use core::raw;
 pub use core::result;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::option;
-
-pub mod error;
-
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use alloc::boxed;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use alloc::rc;
-
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::borrow;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::fmt;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::slice;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::str;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::string;
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use core_collections::vec;
-
-#[stable(feature = "rust1", since = "1.0.0")]
-pub use rustc_unicode::char;
-
-/* Exported macros */
-
-#[macro_use]
-mod macros;
-
-mod rtdeps;
-
-/* The Prelude. */
-
-pub mod prelude;
-
-
-/* Primitive types */
-
-// NB: slice and str are primitive types too, but their module docs + primitive
-// doc pages are inlined from the public re-exports of core_collections::{slice,
-// str} above.
-
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::isize;
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -414,7 +394,6 @@ pub use core::i16;
 pub use core::i32;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::i64;
-
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::usize;
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -425,42 +404,62 @@ pub use core::u16;
 pub use core::u32;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use core::u64;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use alloc::boxed;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use alloc::rc;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::borrow;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::fmt;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::slice;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::str;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::string;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core_collections::vec;
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use rustc_unicode::char;
 
 #[path = "num/f32.rs"]   pub mod f32;
 #[path = "num/f64.rs"]   pub mod f64;
 
-pub mod ascii;
-
-/* Common traits */
-
-pub mod num;
-
-/* Runtime and platform support */
-
 #[macro_use]
 pub mod thread;
-
+pub mod ascii;
 pub mod collections;
 pub mod env;
+pub mod error;
 pub mod ffi;
 pub mod fs;
 pub mod io;
 pub mod net;
+pub mod num;
 pub mod os;
 pub mod panic;
 pub mod path;
 pub mod process;
 pub mod sync;
 pub mod time;
-mod memchr;
 
+// Platform-abstraction modules
 #[macro_use]
 mod sys_common;
 mod sys;
 
-pub mod rt;
+// Private support modules
 mod panicking;
 mod rand;
+mod memchr;
+
+// This module just defines per-platform native library dependencies
+mod rtdeps;
+
+// The runtime entry point and a few unstable public functions used by the
+// compiler
+pub mod rt;
 
 // Some external utilities of the standard library rely on randomness (aka
 // rustc_back::TempDir and tests) and need a way to get at the OS rng we've got

src/libstd/sys_common/mod.rs

@@ -27,18 +27,6 @@
 use sync::Once;
 use sys;
 
-macro_rules! rtabort {
-    ($($t:tt)*) => (::sys_common::util::abort(format_args!($($t)*)))
-}
-
-macro_rules! rtassert {
-    ($e:expr) => ({
-        if !$e {
-            rtabort!(concat!("assertion failed: ", stringify!($e)))
-        }
-    })
-}
-
 pub mod at_exit_imp;
 #[cfg(any(not(cargobuild), feature = "backtrace"))]
 pub mod backtrace;
@@ -101,6 +89,10 @@ pub fn at_exit<F: FnOnce() + Send + 'static>(f: F) -> Result<(), ()> {
     if at_exit_imp::push(Box::new(f)) {Ok(())} else {Err(())}
 }
 
+macro_rules! rtabort {
+    ($($t:tt)*) => (::sys_common::util::abort(format_args!($($t)*)))
+}
+
 /// One-time runtime cleanup.
 pub fn cleanup() {
     static CLEANUP: Once = Once::new();