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 [email protected] ASF Member, Apache Lucene PMC / Committer Bremen, Germany http://lucene.apache.org/ > -----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/ > >>>> > >>>>
