[rust-dev] rustdoc_ng and normalization of documentation
Heya, I have been planning/scheming a new doc web frontend to go with cmr's rustdoc_ng and in the process I ran into the question of normalization and structuring of the documentation blocks. If we take the net::tcp::accept function for example [1], it has fairly extensive documentation but the way it is rendered in the web docs is just a 1:1 markdown to html conversion. For me the Arguments and Returns blocks should come before the example in the documentation, because this is usually shorter and more important. In the source though keeping these close to the bottom is pretty nice because it keeps them closer to the function signature and the code itself. I see a few options to handle this going forward: - Full reorganization of the doc blocks with special tags/annotations à la javadoc [2], I am not a particular fan of that but for special things it does serve it's purpose and has the advantage of being somewhat widespread. - We standardize on a few heading names like Arguments/Returns/Example/Changes so that those blocks can be extracted and displayed in the preferred order in the docs, and whatever remains is appended after. - Stand-still / keep a free-form format What would everyone prefer? Any other approach? [1] http://static.rust-lang.org/doc/extra/net_tcp.html#function-accept [2] http://en.wikipedia.org/wiki/Javadoc Cheers -- Jordi Boggiano @seldaek - http://nelm.io/jordi ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
Re: [rust-dev] rustdoc_ng and normalization of documentation
On Mon, Jul 15, 2013 at 9:03 AM, Jordi Boggiano j.boggi...@seld.be wrote: [snip] - Full reorganization of the doc blocks with special tags/annotations à la javadoc [2], I am not a particular fan of that but for special things it does serve it's purpose and has the advantage of being somewhat widespread. For some things, we can attach an attribute to the item. For example, https://github.com/mozilla/rust/issues/723 would be included in the documentation somehow, rather than the Javadoc-like solution of in-comment annotation. ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
Re: [rust-dev] rustdoc_ng and normalization of documentation
On 15.07.2013 15:07, Corey Richardson wrote: On Mon, Jul 15, 2013 at 9:03 AM, Jordi Boggiano j.boggi...@seld.be wrote: [snip] - Full reorganization of the doc blocks with special tags/annotations à la javadoc [2], I am not a particular fan of that but for special things it does serve it's purpose and has the advantage of being somewhat widespread. For some things, we can attach an attribute to the item. For example, https://github.com/mozilla/rust/issues/723 would be included in the documentation somehow, rather than the Javadoc-like solution of in-comment annotation. Interesting indeed, and definitely when possible I would favor real annotations to in-comment ones, that way the code won't compile unless the docs format is valid. However as bjz mentioned [1] it would be nice to have more metadata attached to it like an alternative and date/version at which it will disappear. [1] https://github.com/mozilla/rust/issues/723#issuecomment-10351828 Cheers -- Jordi Boggiano @seldaek - http://nelm.io/jordi ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
