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 [email protected] https://mail.mozilla.org/listinfo/rust-dev
