[brailleblaster] Re: Latest Draft of BrailleBlaster attached
- From: "Susan Jolly" <easjolly@xxxxxxxxxxxxx>
- To: <brailleblaster@xxxxxxxxxxxxx>
- Date: Tue, 28 Dec 2010 17:29:58 -0700
John,
I was trying to make less work for you, not more. If you get in the habit
of putting a short package.html file or package-info.java file in the
directory every time you create a package directory, then it just takes an
extra minute or so and your major API documentation is done. Same thing with
putting a one-sentence description of a class just above the class
declaration every time you create a new class.
I was unaware of package-info.java before you mentioned it. Apparently
since Java 1.5 this is the preferred alternative since it allows for
package-level annotations and is less cluttered. However, you can still use
a package.html file if you prefer.
This is a very nice write-up about why and how to use javadoc.
http://www.javapractices.com/topic/TopicAction.do?Id=60
I'd not run across the javapractices site before but it looks really useful.
By the way, javadoc is simply a tool for extracting comments from Java
source code and publishing them in a certain format. This is very different
from literate programming. With a literate programming system you write
your literate source in a higher-level language that intermixes code
snippets and documentation in what Donald Knuth called a Web. You must then
use a preprocessor to turn the literate source into actual source code every
time you want to compile. I don't believe literate programming has ever
really caught on.
Susan
Other related posts:
