On Thu, Jun 20, 2013 at 7:30 PM, Brian Anderson <[email protected]> wrote: > 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. > > [snip] > > 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. >
I think this is a problem with rust overall right now, and it's one of the things that a header system allows quite nicely: usage of API declaration without compilation. I'm not sure what the best way to solve this is, though. The best I can come up with is maybe an `.rmd` file that just contains extracted crate metadata, and that there be a rustc mode that allows this. I don't know the exact details of the metadata: maybe someone else could elaborate on what it is, where it comes from, and what it is used for? (This would fit in with my goal of "replace the monstrosity that is ebml"). It might be worth looking into how .NET or other platforms with similar architecture accomplish this, if at all. > 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. > When discussing this exact thing with SiegeLord I had the idea of partially implementing a resolve pass, but there are so many problems with it that I don't really see it as desirable. I would really like to run the real resolve code, if possible. > 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. > +1, for the general case. Having non-HTML (XML, probably) output is useful for exporting to docbook, or something that can be turned into a PDF (and also for use in IDEs). > 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. > I'll run with this idea, it seems solid. _______________________________________________ Rust-dev mailing list [email protected] https://mail.mozilla.org/listinfo/rust-dev
