RFR: 8268978: Document the javadoc software stack

[Jonathan Gibbons]

On Fri, 21 Jan 2022 16:25:42 GMT, Hannes Wallnöfer <hannesw 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.
>
> 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.

I'll take a look.

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

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