RFR: 8268978: Document the javadoc software stack

[Jonathan Gibbons]

On Mon, 24 Jan 2022 18:51:02 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

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

I think it helps to keep them separate ... and the text is adjacent.

"Other Doclets" is somewhat more about why you might not want to write a doclet these days ... it's addressing the historical past where there were lots of doclets, a lot of which did not even look at doc comments ... i.e they were using the Doclet API as an early Language Model API.

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

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