[Doc-SIG] Documentation tool

[John Mitchell]

On Fri, 19 Jun 1998, Mark Hammond wrote:

> I dont know what [JavaDoc formatting is like].  Is it possible to
> summarize?

Yep. You start a comment with "/**" (instead of "/*", and add in a few
magic tags.  As in:

     /**
      * A class representing a window on the screen.
      * For example:
      * <pre>
      *    Window win = new Window(parent);
      *    win.show();
      * </pre>
      *
      * @see            awt.BaseWindow
      * @see            awt.Button
      * @version        1.2 12 Dec 1994
      * @author         Sami Shaio
      */
      class Window extends BaseWindow {
      ...
      }

More info can be had at:
	http://www.javasoft.com/products/jdk/javadoc/index.html

I like javadoc because it's trivially easy to get your scribbled comments
into nice crosslinked HTML pages, so the code author tends to comment
his/her code better, leading to more reuse, etc.

Documentation is a drag to write.  Why spend braincells on a new
formatting system, when an already-designed one is up and happening?  I
write java a bit, and I'd *really* like a Python flavor of it...


- j