> 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.

I _partly_ agree.

"automatically ... every time I update" ?  You do have to remember to run
the script--or customize the "Save" function of your editor, or tell your
Web server to run it every time it gets a call for an API page.  But
that's not so hard, so I guess I agree with that part.

And I agree (I said so) Ada should have something like this.

Where Ada differs from Java, is that a well-done package spec IS almost
equivalent to javadoc output.  "Adadoc" should make the hyperlinks like
Ada2HTML and javadoc do.  It should also skip the private parts like
javadoc does.  It should make good use of HTML capabilities to make the
spec easier to read.

Where "Adadoc" should NOT emulate javadoc is in making viewers of the
original spec think they have double vision.  Think about it:  these guys
already wrote a java parser and compiler.  Why did it not occur to them
that they do not need to make the programmer repeat his code in comments?
That defeats the goal of "automatic documentation."  Remember one of
Murphy's laws: "Unnecessary duplication soon becomes unnecessary
variation."  (Or see AQ&S-95 3.3.1)