> 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.
Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision: Address (some) feedback ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/7843/files - new: https://git.openjdk.java.net/jdk/pull/7843/files/0ea3ec8c..82368f63 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7843&range=01 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7843&range=00-01 Stats: 9 lines in 9 files changed: 0 ins; 0 del; 9 mod Patch: https://git.openjdk.java.net/jdk/pull/7843.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/7843/head:pull/7843 PR: https://git.openjdk.java.net/jdk/pull/7843
