On Wed, 16 Mar 2022 16:47:12 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
>> This PR started in a draft mode as a refactoring effort. After a few commits >> and chats with Jonathan Gibbons, I decided that further refactoring belongs >> to follow-up PRs and that this PR could be marked as "Ready for review". >> >> The motivation for the initial refactoring effort was as follows. The word >> "tree" is heavily overloaded in the JavaDoc codebase, both in comments and >> code. Here are some of the contexts this word appears in: >> >> * Hierarchy Tree (i.e. overview-tree.html and package-tree.html) >> * DocTree (AST nodes) >> * ClassTree, *TreeWriter (data structures and entities related to >> supertype-subtype relationship) >> * HtmlTree (HTML nodes) and specifically UL/OL elements which are nested >> lists >> >> Sometimes contexts overlap, making the word "tree" ambiguous. To reduce this >> ambiguity, the word "tree" should be dropped in favor of a more specific >> word of phrase where possible. >> >> In the case where the context is >> `jdk.javadoc.internal.doclets.toolkit.Content`, the programmer is already >> aware that they are dealing with trees in the sense that `Content` objects >> support recursive composition. There's no need to have the phrase "content >> tree" where "content" would do. Moreover, in the context that is exclusively >> about `Content` objects, the word "content" can be dropped too, since the >> type information is assumed. >> >> As an example of content overlap, have a look at the source of >> `jdk.javadoc.internal.doclets.toolkit.builders.MemberSummaryBuilder::buildSummary`. >> This method used to needlessly mix DocTree with Content tree. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java > line 298: > >> 296: >> 297: /** >> 298: * Adds use information to the documentation. > > An alternative would be one of > * Adds use information to the given content. > * Adds use information to the specified content. Or, Adds use information for a list of elements to the specified content. @param the list of elements ------------- PR: https://git.openjdk.java.net/jdk/pull/7843
