[Doc-SIG] Documentation tool

[Tim Peters]

> What happened to JavaDoc?  Did this happen?  How much of HTML does it
> support?  Is there pressure to support more?

javadoc only worries about its own tags (@param and @see and so on);
everything else is passed thru, unanalyzed, to its output (which is a web of
HTML files -- a browser is an essential part of the javadoc system).

So javadoc "supports" all of HTML (present & future) in user docs simply by
leaving it alone.  The only restriction is that javadoc reserves the heading
tags (<H1>, <H2>, etc) for its own use.  The user *could* use heading tags
too (javadoc won't try to stop them -- it's not trying to analyze the user's
HTML so doesn't even notice), but the result would be confusing to look at.

It's a lovely separation of concerns, but not at all designed for any sort
of introspective or interactive use.

if-all-you-want-is-to-stare-at-your-browser-it's-great-ly y'rs  - tim