rustdoc: Inline documentation across crates

src/doc/rustdoc.md

@@ -41,6 +41,31 @@ pub fn recalibrate() {
 # }
 ~~~
 
+Documentation can also be controlled via the `doc` attribute on items. This is
+implicitly done by the compiler when using the above form of doc comments
+(converting the slash-based comments to `#[doc]` attributes).
+
+~~~
+#[doc = "
+Calculates the factorial of a number.
+
+Given the input integer `n`, this function will calculate `n!` and return it.
+"]
+pub fn factorial(n: int) -> int { if n < 2 {1} else {n * factorial(n)} }
+# fn main() {}
+~~~
+
+The `doc` attribute can also be used to control how rustdoc emits documentation
+in some cases.
+
+```
+// Rustdoc will inline documentation of a `pub use` into this crate when the
+// `pub use` reaches across crates, but this behavior can also be disabled.
+#[doc(no_inline)]
+pub use std::option::Option;
+# fn main() {}
+```
+
 Doc comments are markdown, and are currently parsed with the
 [sundown][sundown] library. rustdoc does not yet do any fanciness such as
 referencing other items inline, like javadoc's `@see`. One exception to this

src/librustc/metadata/common.rs

@@ -206,6 +206,9 @@ pub static tag_crate_triple: uint = 0x66;
 
 pub static tag_dylib_dependency_formats: uint = 0x67;
 
+pub static tag_method_argument_names: uint = 0x8e;
+pub static tag_method_argument_name: uint = 0x8f;
+
 #[deriving(Clone, Show)]
 pub struct LinkMeta {
     pub crateid: CrateId,

src/librustc/metadata/csearch.rs

@@ -306,3 +306,10 @@ pub fn get_missing_lang_items(cstore: &cstore::CStore, cnum: ast::CrateNum)
     let cdata = cstore.get_crate_data(cnum);
     decoder::get_missing_lang_items(&*cdata)
 }
+
+pub fn get_method_arg_names(cstore: &cstore::CStore, did: ast::DefId)
+    -> Vec<String>
+{
+    let cdata = cstore.get_crate_data(did.krate);
+    decoder::get_method_arg_names(&*cdata, did.node)
+}

src/librustc/metadata/decoder.rs

@@ -1309,3 +1309,18 @@ pub fn get_missing_lang_items(cdata: Cmd)
     });
     return result;
 }
+
+pub fn get_method_arg_names(cdata: Cmd, id: ast::NodeId) -> Vec<String> {
+    let mut ret = Vec::new();
+    let method_doc = lookup_item(id, cdata.data());
+    match reader::maybe_get_doc(method_doc, tag_method_argument_names) {
+        Some(args_doc) => {
+            reader::tagged_docs(args_doc, tag_method_argument_name, |name_doc| {
+                ret.push(name_doc.as_str_slice().to_strbuf());
+                true
+            });
+        }
+        None => {}
+    }
+    return ret;
+}

src/librustc/metadata/encoder.rs

@@ -536,6 +536,7 @@ fn encode_reexports(ecx: &EncodeContext,
 fn encode_info_for_mod(ecx: &EncodeContext,
                        ebml_w: &mut Encoder,
                        md: &Mod,
+                       attrs: &[Attribute],
                        id: NodeId,
                        path: PathElems,
                        name: Ident,
@@ -584,6 +585,7 @@ fn encode_info_for_mod(ecx: &EncodeContext,
         debug!("(encoding info for module) encoding reexports for {}", id);
         encode_reexports(ecx, ebml_w, id, path);
     }
+    encode_attributes(ebml_w, attrs);
 
     ebml_w.end_tag();
 }
@@ -774,11 +776,30 @@ fn encode_info_for_method(ecx: &EncodeContext,
         } else {
             encode_symbol(ecx, ebml_w, m.def_id.node);
         }
+        encode_method_argument_names(ebml_w, &*ast_method.decl);
     }
 
     ebml_w.end_tag();
 }
 
+fn encode_method_argument_names(ebml_w: &mut Encoder,
+                                decl: &ast::FnDecl) {
+    ebml_w.start_tag(tag_method_argument_names);
+    for arg in decl.inputs.iter() {
+        ebml_w.start_tag(tag_method_argument_name);
+        match arg.pat.node {
+            ast::PatIdent(_, ref name, _) => {
+                let name = name.segments.last().unwrap().identifier;
+                let name = token::get_ident(name);
+                ebml_w.writer.write(name.get().as_bytes());
+            }
+            _ => {}
+        }
+        ebml_w.end_tag();
+    }
+    ebml_w.end_tag();
+}
+
 fn encode_inlined_item(ecx: &EncodeContext,
                        ebml_w: &mut Encoder,
                        ii: InlinedItemRef) {
@@ -895,7 +916,7 @@ fn encode_info_for_item(ecx: &EncodeContext,
         encode_visibility(ebml_w, vis);
         ebml_w.end_tag();
       }
-      ItemFn(_, fn_style, _, ref generics, _) => {
+      ItemFn(ref decl, fn_style, _, ref generics, _) => {
         add_to_index(item, ebml_w, index);
         ebml_w.start_tag(tag_items_data_item);
         encode_def_id(ebml_w, def_id);
@@ -911,13 +932,15 @@ fn encode_info_for_item(ecx: &EncodeContext,
             encode_symbol(ecx, ebml_w, item.id);
         }
         encode_visibility(ebml_w, vis);
+        encode_method_argument_names(ebml_w, &**decl);
         ebml_w.end_tag();
       }
       ItemMod(ref m) => {
         add_to_index(item, ebml_w, index);
         encode_info_for_mod(ecx,
                             ebml_w,
                             m,
+                            item.attrs.as_slice(),
                             item.id,
                             path,
                             item.ident,
@@ -1317,6 +1340,7 @@ fn encode_info_for_items(ecx: &EncodeContext,
     encode_info_for_mod(ecx,
                         ebml_w,
                         &krate.module,
+                        &[],
                         CRATE_NODE_ID,
                         ast_map::Values([].iter()).chain(None),
                         syntax::parse::token::special_idents::invalid,