Re: javadoc => adadoc?

["Norman H. Cohen" <ncohen@us.ibm.com>]

nabbasi@earthlink.net wrote in message <6pvslq$poo@drn.newsguy.com>...

>it seems to me that the need for adadoc is much less than for java.
>
>in java, there is no separation between the specification and
implementation
>of the package, so one uses the tool javadoc to 'pull out' the
specifications
>into an html nicly formatted output so one can look it and know what the
API
>is.
>
>in Ada, one can simply look at the speification part of the package, no
tool
>is needed to 'pull out' the API out of the body as is the case with java.


While Java does not REQUIRE the separation between specification and
implementation, it certainly ALLOWS it:  A Java programmer can define an
interface and a class implementing that interface, achieving roughly the
same effect as writing a package spec and package body in Ada, and this is a
common Java practice.  (Unlike Ada, Java does not enforce hiding of the
implementation:   Another part of the program can access the implementation
by casting from the interface type to the implementation type.)  Thus
javadoc was not invented to make up for a supposed inability to separate
implementation and interface.

The true benefit of javadoc is the automated generation of hypertext
documentation that can be viewed with a browser.  Indices by package, by
class, and by method name, as well as links to related pages (e.g. from the
declaration of a parameter of type FileFilter in the listFiles method of
class File to the documentation for the FileFilter interface) are generated
automatically.  Tree diagrams showing the ancestors of a class are generated
automatically.  In JDK 1.2, javadoc also generates lists of descendents, and
lists methods that a class inherits from each of its ancestors.

This isn't rocket science, but it's damned convenient in large software
projects.  Any language, particularly an OO language, can benefit from this
kind of tool.

-- Norman Cohen