diff --git a/src/libcore/cleanup.rs b/src/libcore/cleanup.rs
index 35155e683dc..2cf7fc92f12 100644
--- a/src/libcore/cleanup.rs
+++ b/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;
diff --git a/src/libcore/cmath.rs b/src/libcore/cmath.rs
index f01af54e475..881dd959e8a 100644
--- a/src/libcore/cmath.rs
+++ b/src/libcore/cmath.rs
@@ -1,3 +1,4 @@
+#[doc(hidden)]; // FIXME #3538
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];
diff --git a/src/libcore/cmp.rs b/src/libcore/cmp.rs
index 4c4efc13859..420d272a2c3 100644
--- a/src/libcore/cmp.rs
+++ b/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;
diff --git a/src/libcore/comm.rs b/src/libcore/comm.rs
index 9f272b50408..cdf5224a071 100644
--- a/src/libcore/comm.rs
+++ b/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;
diff --git a/src/libcore/core.rc b/src/libcore/core.rc
index 8566c5e1070..96d8db5a1e2 100644
--- a/src/libcore/core.rc
+++ b/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];
 
diff --git a/src/libcore/core.rs b/src/libcore/core.rs
index 47ff32a855b..2feb75a71fa 100644
--- a/src/libcore/core.rs
+++ b/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;
diff --git a/src/libcore/dlist.rs b/src/libcore/dlist.rs
index 375e9239d63..d0474673f83 100644
--- a/src/libcore/dlist.rs
+++ b/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;
 
diff --git a/src/libcore/dvec.rs b/src/libcore/dvec.rs
index 32c40a3f66e..482a326b74f 100644
--- a/src/libcore/dvec.rs
+++ b/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;
 
diff --git a/src/libcore/flate.rs b/src/libcore/flate.rs
index 234f2730233..5f317ee0f07 100644
--- a/src/libcore/flate.rs
+++ b/src/libcore/flate.rs
@@ -1,3 +1,9 @@
+/*!
+
+Simple compression
+
+*/
+
 use libc::{c_void, size_t, c_int};
 
 extern mod rustrt {
diff --git a/src/libcore/from_str.rs b/src/libcore/from_str.rs
index f14061633d4..6867db7c431 100644
--- a/src/libcore/from_str.rs
+++ b/src/libcore/from_str.rs
@@ -1,3 +1,5 @@
+//! The trait for types that can be created from strings
+
 use option::Option;
 
 trait FromStr {
diff --git a/src/libcore/gc.rs b/src/libcore/gc.rs
index b1432bc39f5..b86c9e82780 100644
--- a/src/libcore/gc.rs
+++ b/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
diff --git a/src/libcore/io.rs b/src/libcore/io.rs
index 2de7da0480e..96ef5c5f001 100644
--- a/src/libcore/io.rs
+++ b/src/libcore/io.rs
@@ -1,7 +1,7 @@
-/*
-Module: io
+/*!
 
 Basic input/output
+
 */
 
 use result::Result;
diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs
index bce118e09af..7bc356ce812 100644
--- a/src/libcore/iter.rs
+++ b/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
diff --git a/src/libcore/num.rs b/src/libcore/num.rs
index c414d6190c8..d5872933953 100644
--- a/src/libcore/num.rs
+++ b/src/libcore/num.rs
@@ -1,4 +1,4 @@
-/// An interface for numbers.
+//! An interface for numeric types
 
 trait Num {
     // FIXME: Trait composition. (#2616)
diff --git a/src/libcore/path.rs b/src/libcore/path.rs
index b6854ea7ea4..80dfab3fbef 100644
--- a/src/libcore/path.rs
+++ b/src/libcore/path.rs
@@ -1,3 +1,9 @@
+/*!
+
+Cross-platform file path handling
+
+*/
+
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];
diff --git a/src/libcore/reflect.rs b/src/libcore/reflect.rs
index c95d1e6ca57..b7c718b3420 100644
--- a/src/libcore/reflect.rs
+++ b/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;
diff --git a/src/libcore/repr.rs b/src/libcore/repr.rs
index 435f1a5d18d..f779078ed86 100644
--- a/src/libcore/repr.rs
+++ b/src/libcore/repr.rs
@@ -1,3 +1,9 @@
+/*!
+
+More runtime type reflection
+
+*/
+
 use dvec::DVec;
 use io::{Writer, WriterUtil};
 use libc::c_void;
diff --git a/src/libcore/stackwalk.rs b/src/libcore/stackwalk.rs
index 3a07186b011..90f0c4020bf 100644
--- a/src/libcore/stackwalk.rs
+++ b/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;
diff --git a/src/libcore/to_bytes.rs b/src/libcore/to_bytes.rs
index 68000324623..0519347e438 100644
--- a/src/libcore/to_bytes.rs
+++ b/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)];
diff --git a/src/libcore/to_str.rs b/src/libcore/to_str.rs
index 358ad0e281f..65d9b0e4471 100644
--- a/src/libcore/to_str.rs
+++ b/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)];
diff --git a/src/libcore/unicode.rs b/src/libcore/unicode.rs
index cdd2efbd8c3..2c115fcf444 100644
--- a/src/libcore/unicode.rs
+++ b/src/libcore/unicode.rs
@@ -1,3 +1,4 @@
+#[doc(hidden)]; // FIXME #3538
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];
diff --git a/src/libcore/unit.rs b/src/libcore/unit.rs
index 2b09425f752..23b9a4f3be5 100644
--- a/src/libcore/unit.rs
+++ b/src/libcore/unit.rs
@@ -1,6 +1,8 @@
-/**
- * Functions for the unit type.
- */
+/*!
+
+Functions for the unit type.
+
+*/
 
 use cmp::{Eq, Ord};
 
diff --git a/src/libcore/util.rs b/src/libcore/util.rs
index 39589419beb..e27a3cdb18d 100644
--- a/src/libcore/util.rs
+++ b/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 }