Re: javadoc => adadoc?

[kilgallen@eisner.decus.org (Larry Kilgallen)]

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. For example, one critical aspect of documentation is
> to say what you did NOT do and why you did NOT do it!

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.

Larry Kilgallen