graydon/rust — Issue #1077: Write rustdoc
Author: brson
Created: 2011-10-27 02:16:53+00:00
State: open
Labels: feature, unassigned

We probably want our own system to extract documentation from source code. Graydon has mentioned in the past an interest in using syntax extension for this, but a javadoc analogue seems fine.

The two general-purpose systems I've looked into, doxygen and naturaldocs, both have significant downsides. Doxygen requires a filter to translate the source code to something C++-like so I suspect would never give very satisfying results. Naturaldocs isn't widely used and, by default, doesn't understand enough about the structure of the code to establish the correct hierarchies. It might be made to work more nicely with some effort.

Right now we're using naturaldocs just to get something working, but I think we should just roll our own - that seems how most languages do it.