ClassFile.Option Documentation

[-]

Hello,
I think that we can consider removing the Options section from the package
summary.

Back in an earlier iteration, as seen in JDK 21, [1] the options were
listed in a few methods, and there was no way to see the exhaustive list of
options.
However, with the refactor of ClassFile Options into a sealed interface
hierarchy, all these options are now available in the permits list and the
sealed graph (which, due to poor handling of nested classes, is not
available ATM), so there's not that much value keeping a separate list in
the package summary that may be out-of-date.

For marking options as the default in the enum constants, I agree that is a
good idea. A simple paragraph like <p>This is the default option. may work.
In addition, I think we can change the {@code } references to the default
constants to {@link } to improve accessibility.

Chen Liang

[1]:
https://git.openjdk.org/jdk21/blob/890adb6410dab4606a4f26a942aed02fb2f55387/src/java.base/share/classes/jdk/internal/classfile/Classfile.java#L67
[2]:
https://download.java.net/java/early_access/jdk22/docs/api/java.base/java/lang/classfile/ClassFile.Option.html

On Mon, Jan 29, 2024 at 8:21 AM david32768 at btinternet.com
david32768 at btinternet.com <david32768 at btinternet.com> wrote:

> In the ClassFile package description under OPTIONS there is no mention of
> DEADCODE.
>
>
> For a ClassFile.Option enum the default is only mentioned in the enum
> description
>
> but not in the enum constant detailed description.
>
>
> Should all the default options be listed in the detailed description of
> the ClassFile.of methods
>
> as these methods presumably decide what the defaults are.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/classfile-api-dev/attachments/20240129/c500edfe/attachment.htm>