Summary

Massive improvements to the documentation of java.lang.classfile.

Problem

The java.lang.classfile package is shipped with bare documentation besides its package summary. Additional documentation may help users to better understand the features of each model, the transformation mechanism, CodeBuilder, ClassFile constants, and ClassFile.Options.

Solution

Below is the summary of this API specification improvement effort:

1. The general API arrangement of "model", "element", "builder", "transform" setup for classes, methods, fields, and method body; including CompoundElement, ClassFileElement, ClassFileBuilder, ClassFileTransform, and their subtypes in the sealed hierarchy.
2. Concrete subtypes of these API arrangements have special perks, such as where to obtain them, mentioned. Also special notes, such as MethodBuilder static flag cannot be reset, CodeBuilder affected by some options, some elements have special traversal rules or don't appear in traversal at all, lifting of lower transforms to higher ones, etc. are added.
3. The remaining less-documented member structures, such as AccessFlags, ClassFileVersion, Superclass, Interfaces.
4. The ClassFile.Options, and the error-prone details with them, especially AttributeMapperOption and ClassHierarchyResolverOption. Helps users to understand the exact role and background of the options.
5. General stylistic and wording improvement, such as in CodeBuilder and AnnotationValue. In particular, improved specification for many methods in CodeBuilder and constants in ClassFile.
6. Addition of general contracts (IAE at any accessor method and in failed class building) to the package summary. Since the package summary already has a detailed guide, minimal changes were done to it.

See the attached APIDiff for the full extent of the changes.

Specification

See attached apidiff. Note that latest javadoc and apidiff are available on CR site for review.

Note that for Java SE 24, the ClassFile.JAVA_25_VERSION field does not exist; the corresponding documentation improvement to that field will not be backported to 24.