rustdoc: Add rustdocs

src/rustdoc/astsrv.rs

@@ -1,4 +1,11 @@
-#[doc = "Provides all access to AST-related, non-sendable info"];
+#[doc(
+    brief = "Provides all access to AST-related, non-sendable info",
+    desc =
+    "Rustdoc is intended to be parallel, and the rustc AST is filled \
+     with shared boxes. The AST service attempts to provide a single \
+     place to query AST-related information, shielding the rest of \
+     Rustdoc from its non-sendableness."
+)];
 
 import rustc::syntax::ast;
 import rustc::middle::ast_map;

src/rustdoc/attr_parser.rs

@@ -1,3 +1,10 @@
+#[doc(
+    brief = "Attribute parsing",
+    desc =
+    "The attribute parser provides methods for pulling documentation out of \
+     an AST's attributes."
+)];
+
 import rustc::syntax::ast;
 import rustc::front::attr;
 import core::tuple;

src/rustdoc/attr_pass.rs

@@ -1,3 +1,11 @@
+#[doc(
+    brief = "The attribute parsing pass",
+    desc =
+    "Traverses the document tree, pulling relevant documention out of the \
+     corresponding AST nodes. The information gathered here is the basis \
+     of the natural-language documentation for a crate."
+)];
+
 import rustc::syntax::ast;
 import rustc::middle::ast_map;
 

src/rustdoc/doc.rs

@@ -1,3 +1,5 @@
+#[doc = "The document model"];
+
 type ast_id = int;
 
 type cratedoc = ~{

src/rustdoc/extract.rs

@@ -1,8 +1,10 @@
+#[doc = "Converts the Rust AST to the rustdoc document model"];
+
 import rustc::syntax::ast;
 
 export from_srv, extract;
 
-// FIXME: Want this to be from_srv<T:ast::srv> but it crashes
+#[doc = "Use the AST service to create a document tree"]
 fn from_srv(
     srv: astsrv::srv,
     default_name: str
@@ -12,7 +14,6 @@ fn from_srv(
     }
 }
 
-#[doc = "Converts the Rust AST to the rustdoc document model"]
 fn extract(
     crate: @ast::crate,
     default_name: str

src/rustdoc/gen.rs

@@ -1,3 +1,5 @@
+#[doc = "Generate markdown from a document tree"];
+
 import std::io;
 import std::io::writer_util;
 

src/rustdoc/parse.rs

@@ -1,3 +1,5 @@
+#[doc = "AST-parsing helpers"];
+
 import rustc::driver::diagnostic;
 import rustc::syntax::ast;
 import rustc::syntax::codemap;

src/rustdoc/prune_undoc_pass.rs

@@ -1,3 +1,5 @@
+#[doc = "Prunes branches of the document tree that contain no documentation"];
+
 export mk_pass;
 
 fn mk_pass() -> pass {

src/rustdoc/rustdoc.rs

@@ -2,8 +2,10 @@
  * Copyright 2011 Google Inc.
  */
 
+#[doc = "A single operation on the document model"]
 type pass = fn~(srv: astsrv::srv, doc: doc::cratedoc) -> doc::cratedoc;
 
+#[doc = "Run a series of passes over the document"]
 fn run_passes(
     srv: astsrv::srv,
     doc: doc::cratedoc,

src/rustdoc/tystr_pass.rs

@@ -1,3 +1,6 @@
+#[doc =
+  "Pulls type information out of the AST and attaches it to the document"];
+
 import rustc::syntax::ast;
 import rustc::syntax::print::pprust;
 import rustc::middle::ast_map;