auto merge of #9704 : alexcrichton/rust/rustdoc-comments, r=huonw

This addresses some of @huonw's in #9691 about the startling lack of
documentation guiding one throughout the innards of rustdoc::html

r? @huonw

Author: bors

src/librustdoc/html/escape.rs

@@ -8,8 +8,15 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! HTML Escaping
+//!
+//! This module contains one unit-struct which can be used to HTML-escape a
+//! string of text (for use in a format string).
+
 use std::fmt;
 
+/// Wrapper struct which will emit the HTML-escaped version of the contained
+/// string when passed to a format string.
 pub struct Escape<'self>(&'self str);
 
 impl<'self> fmt::Default for Escape<'self> {

src/librustdoc/html/format.rs

@@ -8,6 +8,13 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! HTML formatting module
+//!
+//! This module contains a large number of `fmt::Default` implementations for
+//! various types in `rustdoc::clean`. These implementations all currently
+//! assume that HTML output is desired, although it may be possible to redesign
+//! them in the future to instead emit any format desired.
+
 use std::fmt;
 use std::local_data;
 use std::rt::io;
@@ -19,8 +26,13 @@ use clean;
 use html::render;
 use html::render::{cache_key, current_location_key};
 
+/// Helper to render an optional visibility with a space after it (if the
+/// visibility is preset)
 pub struct VisSpace(Option<ast::visibility>);
+/// Similarly to VisSpace, this structure is used to render a purity with a
+/// space after it.
 pub struct PuritySpace(ast::purity);
+/// Wrapper struct for properly emitting a method declaration.
 pub struct Method<'self>(&'self clean::SelfTy, &'self clean::FnDecl);
 
 impl fmt::Default for clean::Generics {
@@ -98,6 +110,8 @@ impl fmt::Default for clean::Path {
     }
 }
 
+/// Used when rendering a `ResolvedPath` structure. This invokes the `path`
+/// rendering function with the necessary arguments for linking to a local path.
 fn resolved_path(w: &mut io::Writer, id: ast::NodeId, p: &clean::Path,
                  print_all: bool) {
     path(w, p, print_all,
@@ -115,6 +129,8 @@ fn resolved_path(w: &mut io::Writer, id: ast::NodeId, p: &clean::Path,
         });
 }
 
+/// Used when rendering an `ExternalPath` structure. Like `resolved_path` this
+/// will invoke `path` with proper linking-style arguments.
 fn external_path(w: &mut io::Writer, p: &clean::Path, print_all: bool,
                  fqn: &[~str], kind: clean::TypeKind, crate: ast::CrateNum) {
     path(w, p, print_all,
@@ -230,6 +246,7 @@ fn path(w: &mut io::Writer, path: &clean::Path, print_all: bool,
     }
 }
 
+/// Helper to render type parameters
 fn typarams(w: &mut io::Writer, typarams: &Option<~[clean::TyParamBound]>) {
     match *typarams {
         Some(ref params) => {

src/librustdoc/html/markdown.rs

@@ -10,11 +10,28 @@
 
 #[allow(cstack)]; // each rendering task runs on a fixed stack segment.
 
+//! Markdown formatting for rustdoc
+//!
+//! This module implements markdown formatting through the sundown C-library
+//! (bundled into the rust runtime). This module self-contains the C bindings
+//! and necessary legwork to render markdown, and exposes all of the
+//! functionality through a unit-struct, `Markdown`, which has an implementation
+//! of `fmt::Default`. Example usage:
+//!
+//! ```rust
+//! let s = "My *markdown* _text_";
+//! let html = format!("{}", Markdown(s));
+//! // ... something using html
+//! ```
+
 use std::fmt;
 use std::libc;
 use std::rt::io;
 use std::vec;
 
+/// A unit struct which has the `fmt::Default` trait implemented. When
+/// formatted, this struct will emit the HTML corresponding to the rendered
+/// version of the contained markdown string.
 pub struct Markdown<'self>(&'self str);
 
 static OUTPUT_UNIT: libc::size_t = 64;
@@ -110,7 +127,6 @@ impl<'self> fmt::Default for Markdown<'self> {
     fn fmt(md: &Markdown<'self>, fmt: &mut fmt::Formatter) {
         // This is actually common enough to special-case
         if md.len() == 0 { return; }
-
         render(fmt.buf, md.as_slice());
     }
 }