Skip to content

Commit 0fca6c6

Browse files
committed
auto merge of #14391 : alexcrichton/rust/more-rustdoc-inline, r=huonw
As part of the libstd facade (cc #13851), rustdoc is taught to inline documentation across crate boundaries through the usage of a `pub use` statement. This is done to allow libstd to maintain the facade that it is a standalone library with a defined public interface (allowing us to shuffle around what's underneath it). A preview is available at http://people.mozilla.org/~acrichton/doc/std/index.html
2 parents 1cf1527 + 3100bc5 commit 0fca6c6

File tree

14 files changed

+734
-177
lines changed

14 files changed

+734
-177
lines changed

src/doc/rustdoc.md

+25
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,31 @@ pub fn recalibrate() {
4141
# }
4242
~~~
4343

44+
Documentation can also be controlled via the `doc` attribute on items. This is
45+
implicitly done by the compiler when using the above form of doc comments
46+
(converting the slash-based comments to `#[doc]` attributes).
47+
48+
~~~
49+
#[doc = "
50+
Calculates the factorial of a number.
51+
52+
Given the input integer `n`, this function will calculate `n!` and return it.
53+
"]
54+
pub fn factorial(n: int) -> int { if n < 2 {1} else {n * factorial(n)} }
55+
# fn main() {}
56+
~~~
57+
58+
The `doc` attribute can also be used to control how rustdoc emits documentation
59+
in some cases.
60+
61+
```
62+
// Rustdoc will inline documentation of a `pub use` into this crate when the
63+
// `pub use` reaches across crates, but this behavior can also be disabled.
64+
#[doc(no_inline)]
65+
pub use std::option::Option;
66+
# fn main() {}
67+
```
68+
4469
Doc comments are markdown, and are currently parsed with the
4570
[sundown][sundown] library. rustdoc does not yet do any fanciness such as
4671
referencing other items inline, like javadoc's `@see`. One exception to this

src/librustc/metadata/common.rs

+3
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,9 @@ pub static tag_crate_triple: uint = 0x66;
206206

207207
pub static tag_dylib_dependency_formats: uint = 0x67;
208208

209+
pub static tag_method_argument_names: uint = 0x8e;
210+
pub static tag_method_argument_name: uint = 0x8f;
211+
209212
#[deriving(Clone, Show)]
210213
pub struct LinkMeta {
211214
pub crateid: CrateId,

src/librustc/metadata/csearch.rs

+7
Original file line numberDiff line numberDiff line change
@@ -306,3 +306,10 @@ pub fn get_missing_lang_items(cstore: &cstore::CStore, cnum: ast::CrateNum)
306306
let cdata = cstore.get_crate_data(cnum);
307307
decoder::get_missing_lang_items(&*cdata)
308308
}
309+
310+
pub fn get_method_arg_names(cstore: &cstore::CStore, did: ast::DefId)
311+
-> Vec<String>
312+
{
313+
let cdata = cstore.get_crate_data(did.krate);
314+
decoder::get_method_arg_names(&*cdata, did.node)
315+
}

src/librustc/metadata/decoder.rs

+15
Original file line numberDiff line numberDiff line change
@@ -1309,3 +1309,18 @@ pub fn get_missing_lang_items(cdata: Cmd)
13091309
});
13101310
return result;
13111311
}
1312+
1313+
pub fn get_method_arg_names(cdata: Cmd, id: ast::NodeId) -> Vec<String> {
1314+
let mut ret = Vec::new();
1315+
let method_doc = lookup_item(id, cdata.data());
1316+
match reader::maybe_get_doc(method_doc, tag_method_argument_names) {
1317+
Some(args_doc) => {
1318+
reader::tagged_docs(args_doc, tag_method_argument_name, |name_doc| {
1319+
ret.push(name_doc.as_str_slice().to_strbuf());
1320+
true
1321+
});
1322+
}
1323+
None => {}
1324+
}
1325+
return ret;
1326+
}

src/librustc/metadata/encoder.rs

+25-1
Original file line numberDiff line numberDiff line change
@@ -536,6 +536,7 @@ fn encode_reexports(ecx: &EncodeContext,
536536
fn encode_info_for_mod(ecx: &EncodeContext,
537537
ebml_w: &mut Encoder,
538538
md: &Mod,
539+
attrs: &[Attribute],
539540
id: NodeId,
540541
path: PathElems,
541542
name: Ident,
@@ -584,6 +585,7 @@ fn encode_info_for_mod(ecx: &EncodeContext,
584585
debug!("(encoding info for module) encoding reexports for {}", id);
585586
encode_reexports(ecx, ebml_w, id, path);
586587
}
588+
encode_attributes(ebml_w, attrs);
587589

588590
ebml_w.end_tag();
589591
}
@@ -774,11 +776,30 @@ fn encode_info_for_method(ecx: &EncodeContext,
774776
} else {
775777
encode_symbol(ecx, ebml_w, m.def_id.node);
776778
}
779+
encode_method_argument_names(ebml_w, &*ast_method.decl);
777780
}
778781

779782
ebml_w.end_tag();
780783
}
781784

785+
fn encode_method_argument_names(ebml_w: &mut Encoder,
786+
decl: &ast::FnDecl) {
787+
ebml_w.start_tag(tag_method_argument_names);
788+
for arg in decl.inputs.iter() {
789+
ebml_w.start_tag(tag_method_argument_name);
790+
match arg.pat.node {
791+
ast::PatIdent(_, ref name, _) => {
792+
let name = name.segments.last().unwrap().identifier;
793+
let name = token::get_ident(name);
794+
ebml_w.writer.write(name.get().as_bytes());
795+
}
796+
_ => {}
797+
}
798+
ebml_w.end_tag();
799+
}
800+
ebml_w.end_tag();
801+
}
802+
782803
fn encode_inlined_item(ecx: &EncodeContext,
783804
ebml_w: &mut Encoder,
784805
ii: InlinedItemRef) {
@@ -895,7 +916,7 @@ fn encode_info_for_item(ecx: &EncodeContext,
895916
encode_visibility(ebml_w, vis);
896917
ebml_w.end_tag();
897918
}
898-
ItemFn(_, fn_style, _, ref generics, _) => {
919+
ItemFn(ref decl, fn_style, _, ref generics, _) => {
899920
add_to_index(item, ebml_w, index);
900921
ebml_w.start_tag(tag_items_data_item);
901922
encode_def_id(ebml_w, def_id);
@@ -911,13 +932,15 @@ fn encode_info_for_item(ecx: &EncodeContext,
911932
encode_symbol(ecx, ebml_w, item.id);
912933
}
913934
encode_visibility(ebml_w, vis);
935+
encode_method_argument_names(ebml_w, &**decl);
914936
ebml_w.end_tag();
915937
}
916938
ItemMod(ref m) => {
917939
add_to_index(item, ebml_w, index);
918940
encode_info_for_mod(ecx,
919941
ebml_w,
920942
m,
943+
item.attrs.as_slice(),
921944
item.id,
922945
path,
923946
item.ident,
@@ -1317,6 +1340,7 @@ fn encode_info_for_items(ecx: &EncodeContext,
13171340
encode_info_for_mod(ecx,
13181341
ebml_w,
13191342
&krate.module,
1343+
&[],
13201344
CRATE_NODE_ID,
13211345
ast_map::Values([].iter()).chain(None),
13221346
syntax::parse::token::special_idents::invalid,

0 commit comments

Comments
 (0)