I agree too about javadoc. The only thing I would add is obviously the human written content is only as up to date as when it was modified and no tool can tell you if the content becomes out dated. I don't know of any java equivilant of pythons doctest which can make sure examples in docstrings (python's version of javadoc) are correct.
Michael Whapples On 28/12/10 18:23, Sina Bahram wrote:
Agreed, wholeheartedly. Take care, Sina -----Original Message----- From: brailleblaster-bounce@xxxxxxxxxxxxx [mailto:brailleblaster-bounce@xxxxxxxxxxxxx] On Behalf Of Susan Jolly Sent: Tuesday, December 28, 2010 12:41 PM To: brailleblaster@xxxxxxxxxxxxx Subject: [brailleblaster] Re: Latest Draft of BrailleBlaster attached You might want to consider making use of the JavaDoc conventions since JavaDoc provides a nice overview of an API. JavaDoc checks for a package.html file in each subdirectory. This file effectively takes the place of a ReadMe file. A package.html file can be a very simple HTML file with an empty head element. JavaDoc also uses the first sentence of the documentation comment placed immediately before a class or interface declaration as a description for that class or interface in the package summary for a package. SusanJ
