ClassFile.Option Documentation

[Brian Goetz]

The role of the package summary is to tie together the big picture, 
helping the user discover key concepts and find "the end of the string 
to start pulling on." The package summary is where we should say "first 
you need a Classfile object, which will faciliating both reading and 
writing of classfiles, and how it does that can be configured with 
various options."  We can put the option detail with the options, but it 
should be linked from the package Javadoc to help people _discover_ that 
they need to know about options.

On 1/29/2024 9:50 PM, - wrote:
> 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/20240130/867a8acd/attachment.htm>