RFR: 8268978: Document the javadoc software stack

[Jonathan Gibbons]

On Thu, 13 Jan 2022 15:48:59 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> A general question about this: Where and how will this documentation mostly be consumed? The `jdk.javadoc.internal` package is not included in standard JDK documentation, so is it likely that this documentation will be mainly consumed within an editor/IDE?
> 
> My feeling is that maybe a less markup-heavy and more text centric form would be easier to consume in that context. For instance, using appropriate HTML headings and paragraphs instead of the deeply nested `<dl>` structure might provide more of a continuous text experience, while still maintaining the hierarchical information. Of course this is a matter of taste, different people have different preferences.

This is to document the design for the benefit of potential future developers.  I have no illusions that we will ever run javadoc over the internal documentation as a matter of course, but it is getting better/easier to view documentation comments in an editor./IDE, and with that in mind, I note that IntelliJ IDEA does an excellent job in its Reader Mode of displaying the comment and handling the HTML markup.  I also think it is worth keeping relatively high standards for internal documentation, at least for internal public and protected API. (I accept that it is hard to persuade people to better comment private API :-( )

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

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