I love (well written) JavaDoc. It's the best thing since Literate Programming but the biggest pain is that to do any formatting you have write HTML in your Java comments which makes them much less readable at the source code level.
Writing the comments in reStructuredText looks much better as you can actually read them. Well that was the goal of the project.
"reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains."
I hope someone with time on their hands hacks the JavaDoc-er to accept reStructuredText as well.
For examples see the ReStructuredText Quick Start and it's source.
Posted by stuartcw at November 15, 2002 07:00 PM