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.

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.

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

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