RFR: 8283269: Improve definition and use of jdk.javadoc.internal.doclets.toolkit.Content

[Jonathan Gibbons]

On Mon, 21 Mar 2022 18:21:14 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java line 222:
>> 
>>> 220: 
>>> 221:     /**
>>> 222:      * Get the class inheritance tree for the given class.
>> 
>> * Gets
>> 
>> "class inheritance" suggests superclass, which is not a tree. Depending on functional semantics[1], maybe just "class hierarchy", since superclasses do not form a tree and interfaces form an acyclic graph.
>> 
>> [1] impl looks like it is just going up the superclass hierarchy
>
> I picked "inheritance" over "hierarchy" for consistency, because the relevant entities in HTML and CSS referred to "inheritance"; for example:
> 
>  * jdk/javadoc/internal/doclets/formats/html/resources/standard.properties:164
>  * jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java:934
> 
> On the other hand, "hierarchy" was also a good choice because it could be used as a standalone noun, thus eliminating the need for the word "tree".
> 
> Thoughts?

Yes, my criticism was about the use of the word "tree" in this case. While I agree that this is not the primary use you are trying to eliminate (i.e. HtmlTree-like trees) it  nevertheless is misleading to describe the superclasses of a class as forming a tree, since they form just a single branch of any tree.

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

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