-----Original Message-----
From: Jonathan Gibbons <[email protected]>
Sent: Tuesday, March 19, 2019 6:25 PM
To: Uwe Schindler <[email protected]>; [email protected]
Subject: Re: Recnet changes in Javadoc/Javac also affect 3rd party code, is
this going to be
Uwe,
At compile/javac time, doclint is opt-in; at javadoc time, doclint is
opt-out.
You can specify the packages for which doclint should be applied, and
you can refine the set of checks that are applied. The checks on the
headings are covered by the "accessibility" group. If you wish to
disable the accessibility checks, you can use -Xdoclint:-accessibility.
You can see the variety of settings in use in OpenJDK in
make/CompileJavaModules.gmk. Right now, the accessibility checks for
many modules are disabled until we fix the headings. When the headings
are fixed in a module, I expect we will re-enable the checks.
There is no specific JEP for this work; it is being done as bugfix work
to have javadoc able to generate docs that are accessible [1], which
triggered a series of issues related to headings in JDK docs[2]. That
being said, I am planning to update the doc comment spec[3] to document
the relationship between headings and generated docs in doc comments,
with reference to the relevant sections in the W3C spec for HTML 5.
Finally, note that doclint is independent of `--release`. The
`--release` option only sets the equivalent of `-source`, `-target` and
the platform classes (either -Xbootclasspath or --system)
-- Jon
[1]https://bugs.openjdk.java.net/browse/JDK-8215307
[2]https://bugs.openjdk.java.net/issues/?jql=reporter%3Djjg%20and%20sum
mary%20~headings%20and%20labels%20in%20(accessibility)
[3]
https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-
spec.html
On 3/19/19 7:35 AM, Uwe Schindler wrote:
Hi Jon,
of course we want doclint be used on Lucene's source code. We are
perfectly fine to clean up our javadocs, but I was searching the issue tracker:
- What's the JEP for this? I also see discussions about fixing JDK's own class
library to not use H1/H2/H3 headings out of order, but this looks like also
applied to any code enabling doclint, so where is the spec? This is why I
asked if the OpenJDK internal cleanup and the additional checks applied in
javac/javadoc also apply to third party code (in this case "our" code = 3rd
party to the JDK). From the mailing list this only looked like the fixes were
only JDK-internal changes to make Javadocs of JDK better. But by enabling
doclint for all code this gets an issue for code devlopers, too.
- Will this new doclints be in the final version of JDK 13? - if yes, we have to
fix it now! Can we disable only the H1/H2/h3 doclinting in the meantime, but
keep the JDK11/12 ones still active? We are wondering why it's applied,
although code is compiled with "-release 8"!
Sorry for the confusing mail yesterday,
Uwe
-----Original Message-----
From: javadoc-dev <[email protected]> On Behalf
Of
Jonathan Gibbons
Sent: Monday, March 18, 2019 11:08 PM
To: [email protected]
Subject: Re: Recnet changes in Javadoc/Javac also affect 3rd party code, is
this going to be
Uwe,
In addition to my previous answer, I would also note that doclint only
applies to
source code being compiled; if code depends on other libraries, and
those
libraries are made available in compiled form, then doclint will of
course not
be invoked for those libraries.
-- Jon
On 3/18/19 7:38 AM, Jonathan Gibbons wrote:
Uwe,
You can control the set of packages that are analyzed by doclint.
From javac --help-extra
-Xdoclint/package:[-]<packages>(,[-]<package>)*
Enable or disable checks in specific packages. Each <package>
is either the
qualified name of a package or a package name prefix followed
by .*, which
expands to all sub-packages of the given package. Each
<package> can be prefixed
with - to disable checks for the specified package or packages.
-- Jon
On 3/18/19 3:36 AM, Uwe Schindler wrote:
Hi,
I installed OpenJDK 13 preview builds on Apache Lucene's Jenkins (to
actually test some fixes with Hotspot), but the builds did not even
pass compilation phase, so we can't even build Lucene:
https://issues.apache.org/jira/browse/LUCENE-8729
The question is now: We enable "doclint" checks in Lucene's code, but
now it seems to also affect 3rd party code like Apache Lucene, if
Javac has doclint enabled: Is this a bug and will this be part of
JDK13, so will it also be complain in code outside JDK?
My question: How to fix this and what is the correct spec that
handles this for JDK 13?
Uwe
-----
Uwe Schindler
[email protected]
ASF Member, Apache Lucene PMC / Committer
Bremen, Germany
http://lucene.apache.org/
