<!DOCTYPE html><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
<font size="4" face="monospace">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.</font><br>
<br>
<div class="moz-cite-prefix">On 1/29/2024 9:50 PM, - wrote:<br>
</div>
<blockquote type="cite" cite="mid:CABe8uE3MQ8cekR-TgyemXNZGDYwwXZVe9VJXyanbTChaq063vQ@mail.gmail.com">
<div dir="ltr">Hello,
<div>I think that we can consider removing the Options section
from the package summary.</div>
<div><br>
</div>
<div>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.</div>
<div>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.</div>
<div><br>
</div>
<div>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.</div>
<div>In addition, I think we can change the {@code } references
to the default constants to {@link } to improve accessibility.</div>
<div><br>
</div>
<div>Chen Liang</div>
<div><br>
</div>
<div>[1]: <a href="https://git.openjdk.org/jdk21/blob/890adb6410dab4606a4f26a942aed02fb2f55387/src/java.base/share/classes/jdk/internal/classfile/Classfile.java#L67" moz-do-not-send="true" class="moz-txt-link-freetext">https://git.openjdk.org/jdk21/blob/890adb6410dab4606a4f26a942aed02fb2f55387/src/java.base/share/classes/jdk/internal/classfile/Classfile.java#L67</a></div>
<div>[2]: <a href="https://download.java.net/java/early_access/jdk22/docs/api/java.base/java/lang/classfile/ClassFile.Option.html" moz-do-not-send="true" class="moz-txt-link-freetext">https://download.java.net/java/early_access/jdk22/docs/api/java.base/java/lang/classfile/ClassFile.Option.html</a><br>
</div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Mon, Jan 29, 2024 at
8:21 AM <a href="mailto:david32768@btinternet.com" moz-do-not-send="true" class="moz-txt-link-freetext">david32768@btinternet.com</a>
<a href="mailto:david32768@btinternet.com" moz-do-not-send="true" class="moz-txt-link-freetext">david32768@btinternet.com</a>
<<a href="mailto:david32768@btinternet.com" moz-do-not-send="true" class="moz-txt-link-freetext">david32768@btinternet.com</a>>
wrote:<br>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div>
<div dir="auto" style="unicode-bidi:embed">
<p>In the ClassFile package description under OPTIONS
there is no mention of DEADCODE. </p>
<p><br>
</p>
<p>For a ClassFile.Option enum the default is only
mentioned in the enum description</p>
<p> but not in the enum constant detailed description.</p>
<p><br>
</p>
<p>Should all the default options be listed in the
detailed description of the ClassFile.of methods</p>
<p> as these methods presumably decide what the defaults
are.</p>
<div><br>
</div>
</div>
</div>
</blockquote>
</div>
</blockquote>
<br>
</body>
</html>