core: Clean up crate docs and give all mods a brief description

src/libcore/cleanup.rs

@@ -1,3 +1,5 @@
+#[doc(hidden)];
+
 use libc::{c_char, c_void, intptr_t, uintptr_t};
 use ptr::{mut_null, null, to_unsafe_ptr};
 use repr::BoxRepr;

src/libcore/cmath.rs

@@ -1,3 +1,4 @@
+#[doc(hidden)]; // FIXME #3538
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];

src/libcore/cmp.rs

@@ -1,3 +1,15 @@
+/*!
+
+The `Ord` and `Eq` comparison traits
+
+This module contains the definition of both `Ord` and `Eq` which define
+the common interfaces for doing comparison. Both are language items
+that the compiler uses to implement the comparison operators. Rust code
+may implement `Ord` to overload the `<`, `<=`, `>`, and `>=` operators,
+and `Eq` to overload the `==` and `!=` operators.
+
+*/
+
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];
@@ -30,8 +42,6 @@ trait Ord {
     pure fn gt(&&other: self) -> bool;
 }
 
-#[cfg(notest)]
-#[lang="eq"]
 /**
  * Trait for values that can be compared for equality
  * and inequality.
@@ -40,6 +50,8 @@ trait Ord {
  * an `eq` method, with the other generated from
  * a default implementation.
  */
+#[cfg(notest)]
+#[lang="eq"]
 trait Eq {
     pure fn eq(&&other: self) -> bool;
     pure fn ne(&&other: self) -> bool;

src/libcore/comm.rs

@@ -1,31 +1,40 @@
+/*!
+
+Deprecated communication between tasks
+
+Communication between tasks is facilitated by ports (in the receiving
+task), and channels (in the sending task). Any number of channels may
+feed into a single port.  Ports and channels may only transmit values
+of unique types; that is, values that are statically guaranteed to be
+accessed by a single 'owner' at a time.  Unique types include scalars,
+vectors, strings, and records, tags, tuples and unique boxes (`~T`)
+thereof. Most notably, shared boxes (`@T`) may not be transmitted
+across channels.
+
+# Example
+
+~~~
+let po = comm::Port();
+let ch = comm::Chan(po);
+
+do task::spawn {
+    comm::send(ch, "Hello, World");
+}
+
+io::println(comm::recv(p));
+~~~
+
+# Note
+
+Use of this module is deprecated in favor of `core::pipes`. In the
+`core::comm` will likely be rewritten with pipes, at which point it
+will once again be the preferred module for intertask communication.
+
+*/
+
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];
-/*!
- * Communication between tasks
- *
- * Communication between tasks is facilitated by ports (in the receiving
- * task), and channels (in the sending task). Any number of channels may
- * feed into a single port.  Ports and channels may only transmit values
- * of unique types; that is, values that are statically guaranteed to be
- * accessed by a single 'owner' at a time.  Unique types include scalars,
- * vectors, strings, and records, tags, tuples and unique boxes (`~T`)
- * thereof. Most notably, shared boxes (`@T`) may not be transmitted
- * across channels.
- *
- * # Example
- *
- * ~~~
- * let po = comm::Port();
- * let ch = comm::Chan(po);
- *
- * do task::spawn {
- *     comm::send(ch, "Hello, World");
- * }
- *
- * io::println(comm::recv(p));
- * ~~~
- */
 
 use either::Either;
 use libc::size_t;

src/libcore/core.rc

@@ -1,3 +1,27 @@
+/*!
+
+The Rust core library.
+
+The Rust core library provides runtime features required by the language,
+including the task scheduler and memory allocators, as well as library
+support for Rust built-in types, platform abstractions, and other commonly
+used features.
+
+`core` includes modules corresponding to each of the integer types, each of
+the floating point types, the `bool` type, tuples, characters, strings,
+vectors (`vec`), shared boxes (`box`), and unsafe and borrowed pointers
+(`ptr`).  Additionally, `core` provides very commonly used built-in types
+and operations, concurrency primitives, platform abstractions, I/O, and
+complete bindings to the C standard library.
+
+`core` is linked to all crates and its contents imported.  Implicitly, all
+crates behave as if they included the following prologue:
+
+    extern mod core;
+    use core::*;
+
+*/
+
 #[link(name = "core",
        vers = "0.4",
        uuid = "c70c24a7-5551-4f73-8e37-380b11d80be8",
@@ -7,27 +31,6 @@
 #[license = "MIT"];
 #[crate_type = "lib"];
 
-/*!
- * The Rust core library provides functionality that is closely tied to the
- * Rust built-in types and runtime services, or that is used in nearly every
- * non-trivial program.
- *
- * `core` includes modules corresponding to each of the integer types, each of
- * the floating point types, the `bool` type, tuples, characters, strings,
- * vectors (`vec`), shared boxes (`box`), and unsafe pointers (`ptr`).
- * Additionally, `core` provides very commonly used built-in types and
- * operations, concurrency primitives, platform abstractions, I/O, and
- * complete bindings to the C standard library.
- *
- * `core` is linked by default to all crates and the contents imported.
- * Implicitly, all crates behave as if they included the following prologue:
- *
- *     use core;
- *     import core::*;
- *
- * This behavior can be disabled with the `#[no_core]` crate attribute.
- */
-
 // Don't link to core. We are core.
 #[no_core];
 

src/libcore/core.rs

@@ -82,6 +82,7 @@ const debug : u32 = 3_u32;
 // A curious inner-module that's not exported that contains the binding
 // 'core' so that macro-expanded references to core::error and such
 // can be resolved within libcore.
+#[doc(hidden)] // FIXME #3538
 mod core {
     const error : u32 = 0_u32;
     const warn : u32 = 1_u32;

src/libcore/dlist.rs

@@ -1,13 +1,17 @@
+/*!
+
+A doubly-linked list. Supports O(1) head, tail, count, push, pop, etc.
+
+# Safety note
+
+Do not use ==, !=, <, etc on doubly-linked lists -- it may not terminate.
+
+*/
+
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];
 
-/**
- * A doubly-linked list. Supports O(1) head, tail, count, push, pop, etc.
- *
- * Do not use ==, !=, <, etc on doubly-linked lists -- it may not terminate.
- */
-
 export DList;
 export new_dlist, from_elem, from_vec, extensions;
 

src/libcore/dvec.rs

@@ -1,14 +1,18 @@
+/*!
+
+Dynamic vector
+
+A growable vector that makes use of unique pointers so that the
+result can be sent between tasks and so forth.
+
+Note that recursive use is not permitted.
+
+*/
+
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];
 
-// Dynamic Vector
-//
-// A growable vector that makes use of unique pointers so that the
-// result can be sent between tasks and so forth.
-//
-// Note that recursive use is not permitted.
-
 use cast::reinterpret_cast;
 use ptr::null;
 

src/libcore/flate.rs

@@ -1,3 +1,9 @@
+/*!
+
+Simple compression
+
+*/
+
 use libc::{c_void, size_t, c_int};
 
 extern mod rustrt {

src/libcore/from_str.rs

@@ -1,3 +1,5 @@
+//! The trait for types that can be created from strings
+
 use option::Option;
 
 trait FromStr {

src/libcore/gc.rs

@@ -1,4 +1,4 @@
-/*! Precise Garbage Collector
+/*! Precise garbage collector
 
 The precise GC exposes two functions, gc and
 cleanup_stack_for_failure. The gc function is the entry point to the

src/libcore/io.rs

@@ -1,7 +1,7 @@
-/*
+/*!
-Module: io
 
 Basic input/output
+
 */
 
 use result::Result;

src/libcore/iter.rs

@@ -1,3 +1,9 @@
+/*!
+
+The iteration traits and common implementation
+
+*/
+
 use cmp::{Eq, Ord};
 
 /// A function used to initialize the elements of a sequence

src/libcore/num.rs

@@ -1,4 +1,4 @@
-/// An interface for numbers.
+//! An interface for numeric types
 
 trait Num {
     // FIXME: Trait composition. (#2616)

src/libcore/path.rs

@@ -1,3 +1,9 @@
+/*!
+
+Cross-platform file path handling
+
+*/
+
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];

src/libcore/reflect.rs

@@ -1,7 +1,8 @@
 /*!
- * Helper types for interfacing with the `intrinsic::visit_ty`
+
- * reflection system.
+Runtime type reflection
- */
+
+*/
 
 use intrinsic::{TyDesc, get_tydesc, visit_tydesc, TyVisitor};
 use libc::c_void;

src/libcore/repr.rs

@@ -1,3 +1,9 @@
+/*!
+
+More runtime type reflection
+
+*/
+
 use dvec::DVec;
 use io::{Writer, WriterUtil};
 use libc::c_void;

src/libcore/stackwalk.rs

@@ -1,4 +1,4 @@
-// NB: Don't rely on other core mods here as this has to move into the rt
+#[doc(hidden)]; // FIXME #3538
 
 use cast::reinterpret_cast;
 use ptr::offset;

src/libcore/to_bytes.rs

@@ -1,3 +1,9 @@
+/*!
+
+The `ToBytes` and `IterBytes` traits
+
+*/
+
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];

src/libcore/to_str.rs

@@ -1,3 +1,9 @@
+/*!
+
+The `ToStr` trait for converting to strings
+
+*/
+
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];

src/libcore/unicode.rs

@@ -1,3 +1,4 @@
+#[doc(hidden)]; // FIXME #3538
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];

src/libcore/unit.rs

@@ -1,6 +1,8 @@
-/**
+/*!
- * Functions for the unit type.
+
- */
+Functions for the unit type.
+
+*/
 
 use cmp::{Eq, Ord};
 

src/libcore/util.rs

@@ -1,13 +1,15 @@
+/*!
+
+Miscellaneous helpers for common patterns.
+
+*/
+
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];
 
 use cmp::Eq;
 
-/**
- * Miscellaneous helpers for common patterns.
- */
-
 /// The identity function.
 #[inline(always)]
 pure fn id<T>(+x: T) -> T { move x }