On Wed, 16 Mar 2022 16:32:09 GMT, Pavel Rappo <[email protected]> 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.
Some stats on the effects of this PR.
Before:
$ egrep -R '(T|t)ree' src/jdk.javadoc/ | wc -l
4448
$ egrep -R '(C|c)ontent' src/jdk.javadoc/ | wc -l
3934
After:
$ egrep -R '(T|t)ree' src/jdk.javadoc/ | wc -l
2820
$ egrep -R '(C|c)ontent' src/jdk.javadoc/ | wc -l
3836
-------------
PR: https://git.openjdk.java.net/jdk/pull/7843
