From e23e45bc6d7696fa9d69ae9f8f59628eec2cbb03 Mon Sep 17 00:00:00 2001
From: Brian Anderson <banderson@mozilla.com>
Date: Tue, 17 Jan 2012 17:44:32 -0800
Subject: [PATCH] rustdoc: Add rustdocs

---
 src/rustdoc/astsrv.rs           | 9 ++++++++-
 src/rustdoc/attr_parser.rs      | 7 +++++++
 src/rustdoc/attr_pass.rs        | 8 ++++++++
 src/rustdoc/doc.rs              | 2 ++
 src/rustdoc/extract.rs          | 5 +++--
 src/rustdoc/gen.rs              | 2 ++
 src/rustdoc/parse.rs            | 2 ++
 src/rustdoc/prune_undoc_pass.rs | 2 ++
 src/rustdoc/rustdoc.rs          | 2 ++
 src/rustdoc/tystr_pass.rs       | 3 +++
 10 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/src/rustdoc/astsrv.rs b/src/rustdoc/astsrv.rs
index d589cba107b..4bdf4498d63 100644
--- a/src/rustdoc/astsrv.rs
+++ b/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;
diff --git a/src/rustdoc/attr_parser.rs b/src/rustdoc/attr_parser.rs
index 10e4a8af2fe..beec9e0301d 100644
--- a/src/rustdoc/attr_parser.rs
+++ b/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;
diff --git a/src/rustdoc/attr_pass.rs b/src/rustdoc/attr_pass.rs
index 53304341778..c333dc2e365 100644
--- a/src/rustdoc/attr_pass.rs
+++ b/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;
 
diff --git a/src/rustdoc/doc.rs b/src/rustdoc/doc.rs
index 8dd165cf959..8fb3c6bc53e 100644
--- a/src/rustdoc/doc.rs
+++ b/src/rustdoc/doc.rs
@@ -1,3 +1,5 @@
+#[doc = "The document model"];
+
 type ast_id = int;
 
 type cratedoc = ~{
diff --git a/src/rustdoc/extract.rs b/src/rustdoc/extract.rs
index 066ef8817ef..51acade36cf 100644
--- a/src/rustdoc/extract.rs
+++ b/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
diff --git a/src/rustdoc/gen.rs b/src/rustdoc/gen.rs
index fd46cc2b17e..02cf9a99c41 100644
--- a/src/rustdoc/gen.rs
+++ b/src/rustdoc/gen.rs
@@ -1,3 +1,5 @@
+#[doc = "Generate markdown from a document tree"];
+
 import std::io;
 import std::io::writer_util;
 
diff --git a/src/rustdoc/parse.rs b/src/rustdoc/parse.rs
index aab938e4443..ae6ce36136c 100644
--- a/src/rustdoc/parse.rs
+++ b/src/rustdoc/parse.rs
@@ -1,3 +1,5 @@
+#[doc = "AST-parsing helpers"];
+
 import rustc::driver::diagnostic;
 import rustc::syntax::ast;
 import rustc::syntax::codemap;
diff --git a/src/rustdoc/prune_undoc_pass.rs b/src/rustdoc/prune_undoc_pass.rs
index 527c8828033..b431ba6eb68 100644
--- a/src/rustdoc/prune_undoc_pass.rs
+++ b/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 {
diff --git a/src/rustdoc/rustdoc.rs b/src/rustdoc/rustdoc.rs
index e811d8a935f..988d4176e0e 100755
--- a/src/rustdoc/rustdoc.rs
+++ b/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,
diff --git a/src/rustdoc/tystr_pass.rs b/src/rustdoc/tystr_pass.rs
index e31a208d1d1..f94024047c0 100644
--- a/src/rustdoc/tystr_pass.rs
+++ b/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;