Recnet changes in Javadoc/Javac also affect 3rd party code, is this going to be

Tue Mar 19 17:51:19 UTC 2019

Hi,

thanks, so we remove "accessibility" for now when compiling Lucene modules. That's exactly the information I needed. I will make a path and commit this to make builds in JDK13 working again.

IMHO, maybe this should not be enabled by default unless well-documented. I agree with opt-in or opt-out, but this makes perfectly valid and doclinted javadocs (according to previous Java versions) suddenly fail compilation.

Uwe

-----
Uwe Schindler
uschindler at apache.org 
ASF Member, Apache Lucene PMC / Committer
Bremen, Germany
http://lucene.apache.org/

> -----Original Message-----
> From: Jonathan Gibbons <jonathan.gibbons at oracle.com>
> Sent: Tuesday, March 19, 2019 6:25 PM
> To: Uwe Schindler <uschindler at apache.org>; javadoc-dev at openjdk.java.net
> 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 <javadoc-dev-bounces at openjdk.java.net> On Behalf
> Of
> >> Jonathan Gibbons
> >> Sent: Monday, March 18, 2019 11:08 PM
> >> To: javadoc-dev at openjdk.java.net
> >> 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
> >>>> uschindler at apache.org
> >>>> ASF Member, Apache Lucene PMC / Committer
> >>>> Bremen, Germany
> >>>> http://lucene.apache.org/
> >>>>
> >>>>