On 05/02/2013 03:18 AM, Niko Matsakis wrote:
I often find when writing code that I want to introduce "sections" into my file. Typically I do this like://////////////////////////////////////////////////////// // Node construction // // Methods for constructing new nodes. I find this helpful when browsing through the code. I imagine something similar would be helpful when browsing through rustdocs. Maybe we can find a way to incorporate some sort of "section" to use when grouping items, methods, fields, etc. I imagine we could draw on Markdown's `#`, `##`, `###` notation to define sections, subsections, and so forth, but I'm just not sure how we would let rustdoc know about it, since there is nothing in particular to attach the attribute to. Any thoughts? Is this something other people would like?
Right now rustdoc does not care about the order that things appear in the source, instead sorting items by AST node type. I guess that if we did add a way to break modules into sections then rustdoc could only do that sorting within sections.
As you say though, there's no way currently to attach this sort of information to the AST, which is where rustdoc gets its documentation from. If we *were* to allow rustdoc to interpret this sort of standalone comment, then that throws into question the entire strategy of attaching doc comments to AST nodes.
Tangentially, I do think that rustdoc needs to be rethought generally. What I would like to do is create an HTML prototype that demonstrates what we would like for the docs to look like (encompassing both the standalone docs and the rustdocs) and then adapt rustdoc to output those docs. I don't know if I personally will get to that any time soon though.
_______________________________________________ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
