问题
I've use javadoc, as well as a variety of different XML based doc-generation systems. Javadoc is fine, XML based doc-generators are hideous, with the XML getting all over the comments and turning the comments into soup.
I've looked at markdown, and the fact that it is easily parseable into structured data but also super human-readable would make it perfect for in-code comments, where the readability of both the docs and the plaintext is of utmost importance.
Are there any markdown based doc-generators out there already? Is there any reason why it wouldn't work which I don't know of?
回答1:
There exits some Markdown-Doclets (f.ex. http://www.richardnichols.net/open-source/markdown-doclet/ ) which can be used with JavaDoc.
Maybe you are also interested in the famous doxygen tool. It doesn't use Markdown but the format is very similar to it (f. ex. unordered lists with - etc.).
回答2:
You may try mdoc to generate Markdown based documentation. It reads all the .md files and produces HTML based documentation. It also creates a TOC. Check it out.
来源：https://stackoverflow.com/questions/8469804/markdown-for-automatic-doc-generation