On 06/19/2013 01:01 PM, Corey Richardson wrote:
I am going to rewrite and redesign rustdoc. Current bikeshed:
https://github.com/mozilla/rust/wiki/Bikeshed-rustdoc
Please discuss, give me your feature requests, comments, etc.
This is great news. Here are my thoughts about rustdoc: the next generation.
The most important thing is the presentation - does rustdoc give me the
information I need, and is it easy to understand and navigate?
I'll propose that the only output format that matters is HTML, so focus
on that. I strongly suggest approaching a rustdoc redesign with an
upfront UI design phase. Create an HTML mockup that illustrates an
attractive way to present Rust, iterate on community feedback, then
build the tool to fill in the content.
When rustdoc was originally written the Rust AST was much simpler.
Everything was an 'item', so I figured "we'll just display a tree of
items - no sweat". Shortly after Rust 0.1 of course the AST became much
more nuanced and this model fell apart. There are a few tricky bits that
rustdoc doesn't do right and that must be solved in a successful rewrite.
Firstly, impls and their relationships to traits must be captured in an
intuitive way. The current presentation is atrocious. I'd suggest that
the way to do this is, for each type, provide a list of trait
implementations with links back to the trait definition.
The other major deficiency in rustdoc is with reexports - they are just
not surfaced by rustdoc in any way. This could probably be treated
similarly to impls, with each module listing the reexports with a link
to the original definition.
The big, big problem with both these things is that to do them right
requires running resolve. Running resolve to produce documentation
though is not generally possible because it requires upstream crates to
already be compiled. My preference here is for rustdoc to implement it's
own, much more limited, resolve pass, possibly resorting to heuristics
in some cases. I suspect that a sufficiently educated guess will usually
get the answer right. Where resolution fails we can maybe use attributes
to give rustdoc more hints. Patrick disagrees with me on this.
Regarding HTML generation, I think we should not lean on pandoc so
heavily. rustdoc currently produces a page of markdown at a time to pass
to pandoc. This conversion drops a lot of semantic content on the floor.
We should instead output proper semantic HTML that is tailored to Rust
and only use a markdown renderer to convert small sections of doc
comments to HTML.
And finally, a subtle point regarding the architecture: the core data
structure in rustdoc is a 'document', which is iterated over and refined
through a number of passes. I think this is probably the wrong way to
conceptualize this data structure, and instead it should be considered a
limited AST + documentation metadata, reflecting the code structure, not
the document structure. Only convert it to do document immediately
before rendering.
_______________________________________________
Rust-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/rust-dev
