On Tue, 3 May 2022 20:38:44 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
> As described in the JBS issue, the observed problem is a side-effect of a > related but different issue, which is that record classes are not treated the > same was as enum classes when it comes to generating the class hierarchy in > `ClassTree`. Because record classes are not treated specially/differently, > they are treated as ordinary/plain classes, with the side-effect that the > page for `java.lang.Record` shows `Direct Known Subclasses`. > > The underlying fix is therefore to clone the enum support in `ClassTree` and > related classes, to provide support for record classes. It is possible to do > an extreme minimal clone, but that just clones some of the messy evolution > already there. Instead, the code in `ClassTree` and its clients is refactored > and modernized. > > Previously there were four explicit pairs of member fields, containing data > for different groups (hierarchies) of classes, namely: plain classes, enum > classes, interfaces and annotation interfaces. These fields are most of the > code to support them are moved into some new abstractions to encapsulate > related functionality. > > 1. The main new abstraction in `ClassTree` is `Hierarchy` which provides the > support for the different hierarchies displayed in the generated pages. > 2. A new enum `HierarchyKind` identifies the four existing hierarchies > (listed above) and now a new one, for record classes. The hierarchies > correspond to the different kinds of declared type. > 3. A small new class `SubtypeMap` which is a multi-map for mapping a type > element to its subtypes. This is used in `Hierarchy` and to record the > classes that implement an interfaces. > > Generally, the naming should be clearer and more obvious. The most confusing > name in the old code was `enumSubtypes` which was weird because enum classes > don't have subtypes. It meant "subtypes of supertypes of enum classes". This > was a prime motivator to switch to the `hierarchy` terminology. The variant > spellings of `intfacs` have all been replaced by `interfaces`, and > `classtree` becomes `classTree`. > > *Testing*: a new test case has been added to the `TestRecordTypes.java` test, > which verifies the new record hierarchy is displayed on a a package tree > page. It is not simple to directly test the observed/reported behavior, > because it is specific to the JDK API documentation, and because it is about > the content of the `java.lang.Record` API page. However, manual inspection > and diff comparison between JDK API documentation generated before and after > this change reveals only expected differences. These differences are on the > `java.lang.R4cord` page (where the offending section is no longer displayed) > and on the pages related to the two existing records in JDK ... which are now > listed in `Record Class Hierarchy` sections in the appropriate > `package-tree.html` files. Although I haven't looked into code in detail, I can confirm that the following JDK API pages have been updated and look good: 1. java.base/java/lang/Record.html 2. java.base/java/lang/class-use/Object.html 3. java.base/java/lang/class-use/Record.html 4. java.base/java/lang/package-use.html 5. jdk.jshell/jdk/jshell/package-tree.html 6. jdk.net/jdk/net/package-tree.html 7. overview-tree.html WRT documentation, a hierarchy of records now behave similarly to that of enums. ------------- PR: https://git.openjdk.java.net/jdk/pull/8523
