Skip to content

More rustdoc improvements #9540

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 27, 2013
Merged

More rustdoc improvements #9540

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c429c7c
rustdoc: Fix broken struct field search links
alexcrichton Sep 26, 2013
ca697d3
rustdoc: Generate documentation for foreign items
alexcrichton Sep 26, 2013
6a277dc
rustdoc: Strip implementations of private traits
alexcrichton Sep 26, 2013
42bcf63
rustdoc: Render stability attributes
alexcrichton Sep 26, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions src/librustdoc/clean.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ use its = syntax::parse::token::ident_to_str;
use syntax;
use syntax::ast;
use syntax::ast_util;
use syntax::attr;
use syntax::attr::AttributeMethods;

use std;
Expand Down Expand Up @@ -149,6 +150,8 @@ pub enum ItemEnum {
MethodItem(Method),
StructFieldItem(StructField),
VariantItem(Variant),
ForeignFunctionItem(Function),
ForeignStaticItem(Static),
}

#[deriving(Clone, Encodable, Decodable)]
Expand All @@ -172,6 +175,7 @@ impl Clean<Item> for doctree::Module {
inner: ModuleItem(Module {
items: std::vec::concat(&[self.structs.clean(),
self.enums.clean(), self.fns.clean(),
std::vec::concat(self.foreigns.clean()),
self.mods.clean(), self.typedefs.clean(),
self.statics.clean(), self.traits.clean(),
self.impls.clean(), self.view_items.clean()])
Expand Down Expand Up @@ -203,6 +207,25 @@ impl Clean<Attribute> for ast::Attribute {
}
}

// This is a rough approximation that gets us what we want.
impl<'self> attr::AttrMetaMethods for &'self Attribute {
fn name(&self) -> @str {
match **self {
Word(ref n) | List(ref n, _) | NameValue(ref n, _) =>
n.to_managed()
}
}

fn value_str(&self) -> Option<@str> {
match **self {
NameValue(_, ref v) => Some(v.to_managed()),
_ => None,
}
}
fn meta_item_list<'a>(&'a self) -> Option<&'a [@ast::MetaItem]> { None }
fn name_str_pair(&self) -> Option<(@str, @str)> { None }
}

#[deriving(Clone, Encodable, Decodable)]
pub struct TyParam {
name: ~str,
Expand Down Expand Up @@ -968,6 +991,41 @@ impl Clean<ViewListIdent> for ast::path_list_ident {
}
}

impl Clean<~[Item]> for ast::foreign_mod {
fn clean(&self) -> ~[Item] {
self.items.clean()
}
}

impl Clean<Item> for ast::foreign_item {
fn clean(&self) -> Item {
let inner = match self.node {
ast::foreign_item_fn(ref decl, ref generics) => {
ForeignFunctionItem(Function {
decl: decl.clean(),
generics: generics.clean(),
purity: ast::extern_fn,
})
}
ast::foreign_item_static(ref ty, mutbl) => {
ForeignStaticItem(Static {
type_: ty.clean(),
mutability: if mutbl {Mutable} else {Immutable},
expr: ~"",
})
}
};
Item {
name: Some(self.ident.clean()),
attrs: self.attrs.clean(),
source: self.span.clean(),
id: self.id,
visibility: self.vis.clean(),
inner: inner,
}
}
}

// Utilities

trait ToSource {
Expand Down
2 changes: 2 additions & 0 deletions src/librustdoc/doctree.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ pub struct Module {
traits: ~[Trait],
vis: ast::visibility,
impls: ~[Impl],
foreigns: ~[ast::foreign_mod],
view_items: ~[ast::view_item],
}

Expand All @@ -50,6 +51,7 @@ impl Module {
traits : ~[],
impls : ~[],
view_items : ~[],
foreigns : ~[],
}
}
}
Expand Down
108 changes: 76 additions & 32 deletions src/librustdoc/html/render.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ use extra::json::ToJson;
use extra::sort;

use syntax::ast;
use syntax::attr;

use clean;
use doctree;
Expand Down Expand Up @@ -521,6 +522,14 @@ impl Context {
}
}
}
clean::StructItem(s) => {
let mut it = s.fields.move_iter();
do self.recurse(name) |this| {
for item in it {
f(this, item);
}
}
}
_ => {}
}
}
Expand All @@ -532,19 +541,21 @@ impl Context {

fn shortty(item: &clean::Item) -> &'static str {
match item.inner {
clean::ModuleItem(*) => "mod",
clean::StructItem(*) => "struct",
clean::EnumItem(*) => "enum",
clean::FunctionItem(*) => "fn",
clean::TypedefItem(*) => "typedef",
clean::StaticItem(*) => "static",
clean::TraitItem(*) => "trait",
clean::ImplItem(*) => "impl",
clean::ViewItemItem(*) => "viewitem",
clean::TyMethodItem(*) => "tymethod",
clean::MethodItem(*) => "method",
clean::StructFieldItem(*) => "structfield",
clean::VariantItem(*) => "variant",
clean::ModuleItem(*) => "mod",
clean::StructItem(*) => "struct",
clean::EnumItem(*) => "enum",
clean::FunctionItem(*) => "fn",
clean::TypedefItem(*) => "typedef",
clean::StaticItem(*) => "static",
clean::TraitItem(*) => "trait",
clean::ImplItem(*) => "impl",
clean::ViewItemItem(*) => "viewitem",
clean::TyMethodItem(*) => "tymethod",
clean::MethodItem(*) => "method",
clean::StructFieldItem(*) => "structfield",
clean::VariantItem(*) => "variant",
clean::ForeignFunctionItem(*) => "ffi",
clean::ForeignStaticItem(*) => "ffs",
}
}

Expand All @@ -558,6 +569,18 @@ impl<'self> Item<'self> {

impl<'self> fmt::Default for Item<'self> {
fn fmt(it: &Item<'self>, fmt: &mut fmt::Formatter) {
match attr::find_stability(it.item.attrs.iter()) {
Some(stability) => {
write!(fmt.buf,
"<a class='stability {lvl}' title='{reason}'>{lvl}</a>",
lvl = stability.level.to_str(),
reason = match stability.text {
Some(s) => s, None => @"",
});
}
None => {}
}

// Write the breadcrumb trail header for the top
write!(fmt.buf, "<h1 class='fqn'>");
match it.item.inner {
Expand All @@ -584,12 +607,15 @@ impl<'self> fmt::Default for Item<'self> {
match it.item.inner {
clean::ModuleItem(ref m) => item_module(fmt.buf, it.cx,
it.item, m.items),
clean::FunctionItem(ref f) => item_function(fmt.buf, it.item, f),
clean::FunctionItem(ref f) | clean::ForeignFunctionItem(ref f) =>
item_function(fmt.buf, it.item, f),
clean::TraitItem(ref t) => item_trait(fmt.buf, it.item, t),
clean::StructItem(ref s) => item_struct(fmt.buf, it.item, s),
clean::EnumItem(ref e) => item_enum(fmt.buf, it.item, e),
clean::TypedefItem(ref t) => item_typedef(fmt.buf, it.item, t),
clean::VariantItem(*) => item_variant(fmt.buf, it.cx, it.item),
clean::StructFieldItem(*) => item_struct_field(fmt.buf, it.cx,
it.item),
_ => {}
}
}
Expand Down Expand Up @@ -663,6 +689,10 @@ fn item_module(w: &mut io::Writer, cx: &Context,
(_, &clean::EnumItem(*)) => false,
(&clean::StaticItem(*), _) => true,
(_, &clean::StaticItem(*)) => false,
(&clean::ForeignFunctionItem(*), _) => true,
(_, &clean::ForeignFunctionItem(*)) => false,
(&clean::ForeignStaticItem(*), _) => true,
(_, &clean::ForeignStaticItem(*)) => false,
(&clean::TraitItem(*), _) => true,
(_, &clean::TraitItem(*)) => false,
(&clean::FunctionItem(*), _) => true,
Expand Down Expand Up @@ -690,27 +720,31 @@ fn item_module(w: &mut io::Writer, cx: &Context,
}
curty = myty;
write!(w, "<h2>{}</h2>\n<table>", match myitem.inner {
clean::ModuleItem(*) => "Modules",
clean::StructItem(*) => "Structs",
clean::EnumItem(*) => "Enums",
clean::FunctionItem(*) => "Functions",
clean::TypedefItem(*) => "Type Definitions",
clean::StaticItem(*) => "Statics",
clean::TraitItem(*) => "Traits",
clean::ImplItem(*) => "Implementations",
clean::ViewItemItem(*) => "Reexports",
clean::TyMethodItem(*) => "Type Methods",
clean::MethodItem(*) => "Methods",
clean::StructFieldItem(*) => "Struct Fields",
clean::VariantItem(*) => "Variants",
clean::ModuleItem(*) => "Modules",
clean::StructItem(*) => "Structs",
clean::EnumItem(*) => "Enums",
clean::FunctionItem(*) => "Functions",
clean::TypedefItem(*) => "Type Definitions",
clean::StaticItem(*) => "Statics",
clean::TraitItem(*) => "Traits",
clean::ImplItem(*) => "Implementations",
clean::ViewItemItem(*) => "Reexports",
clean::TyMethodItem(*) => "Type Methods",
clean::MethodItem(*) => "Methods",
clean::StructFieldItem(*) => "Struct Fields",
clean::VariantItem(*) => "Variants",
clean::ForeignFunctionItem(*) => "Foreign Functions",
clean::ForeignStaticItem(*) => "Foreign Statics",
});
}

match myitem.inner {
clean::StaticItem(ref s) => {
clean::StaticItem(ref s) | clean::ForeignStaticItem(ref s) => {
struct Initializer<'self>(&'self str);
impl<'self> fmt::Default for Initializer<'self> {
fn fmt(s: &Initializer<'self>, f: &mut fmt::Formatter) {
if s.len() == 0 { return; }
write!(f.buf, "<code> = </code>");
let tag = if s.contains("\n") { "pre" } else { "code" };
write!(f.buf, "<{tag}>{}</{tag}>",
s.as_slice(), tag=tag);
Expand All @@ -719,7 +753,7 @@ fn item_module(w: &mut io::Writer, cx: &Context,

write!(w, "
<tr>
<td><code>{}static {}: {} = </code>{}</td>
<td><code>{}static {}: {}</code>{}</td>
<td class='docblock'>{}&nbsp;</td>
</tr>
",
Expand Down Expand Up @@ -980,11 +1014,12 @@ fn render_struct(w: &mut io::Writer, it: &clean::Item,
for field in fields.iter() {
match field.inner {
clean::StructFieldItem(ref ty) => {
write!(w, " {}{}: {},\n{}",
write!(w, " {}<a name='field.{name}'>{name}</a>: \
{},\n{}",
VisSpace(field.visibility),
field.name.get_ref().as_slice(),
ty.type_,
tab);
tab,
name = field.name.get_ref().as_slice());
}
_ => unreachable!()
}
Expand Down Expand Up @@ -1170,3 +1205,12 @@ fn item_variant(w: &mut io::Writer, cx: &Context, it: &clean::Item) {
*cx.current.last(),
it.name.get_ref().as_slice());
}

fn item_struct_field(w: &mut io::Writer, cx: &Context, it: &clean::Item) {
write!(w, "<DOCTYPE html><html><head>\
<meta http-equiv='refresh' content='0; \
url=../struct.{}.html\\#field.{}'>\
</head><body></body></html>",
*cx.current.last(),
it.name.get_ref().as_slice());
}
15 changes: 15 additions & 0 deletions src/librustdoc/html/static/main.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,3 +269,18 @@ a {
float: left;
padding: 20px;
}

.stability {
border-left: 5px solid #000;
border-radius: 3px;
padding: 0 3px;
float: right;
background: #fff;
text-transform: lowercase;
}
.stability.Deprecated { border-color: #D60027; color: #880017; }
.stability.Experimental { border-color: #EC5315; color: #a53c0e; }
.stability.Unstable { border-color: #FFD700; color: #b39800; }
.stability.Stable { border-color: #AEC516; color: #7c8b10; }
.stability.Frozen { border-color: #009431; color: #007726; }
.stability.Locked { border-color: #0084B6; color: #00668c; }
Loading