Re: javadoc => adadoc?

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

Larry Kilgallen wrote in message <1998Aug4.073510.1@eisner>...

>In article <dewar.902212445@merv>, dewar@merv.cs.nyu.edu (Robert Dewar)
writes:
>> Norm said
>>
>> <<> 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
>>>>
>>
>> Very nice, but not for a moment would I describe this as documentation!
>> The danger of such tools is precisely that it leads sloppy coders to
>> think that they don't need to document their code, because some automatic
>> tool can do it for them. Documentation is all about providing information
>> that is NOT readily derivable from the code, by either a human or by a
>> simple minded tool.

Of course any decent javadoc documentation includes extensive commentary
written by a human.  The principal job of  javadoc is to reformat annotated
comments about a class, interface, variable, or method into HTML.  The
automatically generated hyperlinks are useful to the extent that they link
you to informative commentary.

Sure, it is possible, and probably even useful, to run javadoc on
commentless files, just to get automatically generated indexes and hypertext
describing class hierarchies, method profiles, and so forth.  However, I
certainly agree that this does not constitute "documentation" of the code.

I don't know how common it is to use javadoc on source code that contains no
javadoc annotations.  I haven't run across such javadoc output myself.  I
heavily comment my own code regardless of whether I expect to run a
documentation-extraction tool on it.  When I code in Java, I adhere to
javadoc conventions for comments describing the overall purpose of a class
or interface and the meanings of a method's parameters, results, and
exceptions, for several reasons.  First, the notation is not TOO unnatural.
:-)  Second, it is a format easily recognized and understood by habitual
readers of Java source code.  Third, it leaves open the possibility that I
will actually feed the source file to javadoc some day.

>>                                     For example, one critical aspect of
documentation is
>> to say what you did NOT do and why you did NOT do it!

Yes, but that is design documentation, and javadoc is intended primarily to
produce documentation for the user of a software component.  Documentation
of a component's design is of interest to someone who is reading the source
code, so it makes sense to place design documentation in ordinary comments
in the source code.  In contrast, javadoc output is targeted to programmers
using the documented classes as black boxes.

>
>I have long felt that such human generated commentary has the best chance
>in most shops of being:
>
> a) maintained
>
> b) read
>
>during subsequent revisions if it is stored as comments in the source code
>itself.  Sentinel characters to denote such special comments may be in
order,
>but it hardly need be so complex as HTML to convey meaning.  Extracting to
>an external format can go through some arbitrary formatting process.

That's precisely what javadoc does.  It reformats specially annotated
comments written by humans.  In JDK 1.1, it reformats this information in
the form of HTML (which is far more difficult to read than the original
annotations if read directly, but extremely convenient to view through a
browser).  In JDK 1.2, there is a package com.sun.javadoc that reads javadoc
annotations and provides an ASIS-like interface for querying the information
that javadoc gathers.  You can write a program that Sun calls a "doclet"
 :-( ) to use the information provided by this interface, and JDK 1.2
includes a default doclet that generates HTML.

Here is an example to help clear up misconceptions about what javadoc does.
The class java.io.FileInputStream has a method named read, declared as
follows:

    /**
     * Reads up to <code>len</code> bytes of data from this input stream
     * into an array of bytes. This method blocks until some input is
     * available.
     *
     * @param      b     the buffer into which the data is read.
     * @param      off   the start offset of the data.
     * @param      len   the maximum number of bytes read.
     * @return     the total number of bytes read into the buffer, or
     *             <code>-1</code> if there is no more data because the end
of
     *             the file has been reached.
     * @exception  IOException  if an I/O error occurs.
     * @since      JDK1.0
     */
    public int read(byte b[], int off, int len) throws IOException {
        return readBytes(b, off, len);
    }

Anything surrounded by /* and */ is a comment in Java, but comments
beginning /** are extracted by javadoc.  Within such a comment, the '@'
character marks an annotation keyword.  The generated HTML can be found at
the following URL:

http://www.javasoft.com/products/jdk/1.1/docs/api/java.io.FileInputStream.ht
ml


Note the indexes to constructors and methods near the top of the page,
containing a one-sentence description of each method and a link to the
complete description.  (The first sentence of the complete description is
always used for the index.)  Click on the third overloaded read method in
the method index and the browser will bing you to the documentation
generated from the annotated source code above.  Click on any of the
hyperlinks to see other examples of javadoc output.

To summarize, javadoc is a handy tool which can provide effective
component-user documentation when used in a conscientiously applied program
of thorough commentary.  It does not produce design documentation, and it
does not produce decent user documentation without human effort.  Ada would
benefit from a similar tool.  (Wasn't a grad student at GWU working on one a
couple of years ago?)

-- Norman Cohen