RFR: 8268978: Document the javadoc software stack

[Hannes Wallnöfer]

On Wed, 22 Dec 2021 00:48:08 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a `noreg-doc` update to document the javadoc software stack, in the top-level `jdk.javadoc.internal` package.
> 
> The intent is to provide a broad overview.   We can add more specific details, but in general, additional details would probably be better in the `package-info` files for the constituent packages.

This is a very useful overview and introduction!

It looks very good to me, except I think the information in "Other Doclets" should be merged with or added to the "Doclet Interface" section as described below.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/package-info.java line 121:

> 119:  *          Which is best for any application will depend of the circumstances, but
> 120:  *          if a tool does not need access to the documentation comments in a program,
> 121:  *          it is possible that one of the other invocation mechanisms will be more convenient.

Should the "Other Doclets" part above be added to the "Doclet Interface" section below? I think they deal with very related topics. The text above goes into some detail about when and how to implement doclets, which is the topic of the text below. Also, the list above mostly describes the actual components of the javadoc module, but "Other Doclets" is not really part of that.

-------------

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/6914