W. Wesley Groleau x4923 wrote:

> javadoc: more hype.  Takes from Java source the info that would naturally
> be present in a well-crafted Ada spec, and displays it with attractive
> font sizes: but _only_ if you duplicate the code in special comments and
> if the reader hasn't tampered with his browser's font preferences.

It is more than just attractive fonts really.

If I do :

for file in *.java
javadoc -d ./docs $file

and in my docs directory I have an updated  html file for each java file
and a master file I can use by browser to navigate those files by simple
html click on the links to look at all the API's of all my classes and
list of member variables etc..   I can send my docs/ directory to some
to show them latest API overview. I dont have to send my source code.

All what I have to do, is add the tag "@" in the java source files on
the line where I want the javadoc to pull out the text describing the
API and a keyword(s) (for arguments, return value, exceptions raised,
etc...). I have to write the API descrption any way, all what I have to
do is do it in more structured way now.

HTML based documentation of code is very good idea, as long the
documentations are automatically pulled out of the code every time I
update my source code so I don't have to worry about out of date html
files that describes my code.  I can write a script that I run everytime
I want updated documentations, so it is very simple to use, it becomes a
matter of typing a one line command.

It is also more clear to read it from the HTML than from the source,
with all those nice colors and red links showing class dependencies.

I think Ada should have something like this, may be we can choose a
different tag than "@", but the IDEA of javadoc is good, you can argue
on implementation.