On Wed, 22 Dec 2021 00:48:08 GMT, Jonathan Gibbons <j...@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
