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%20summary%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/
