Hi, > That being said, it is always a problem when new warnings are introduced > in tools for new conditions. I apologize for the inconvenience, but I > would say that your existing javadoc comments, and generated > documentation, were not valid from an accessibility standpoint, because > of the headings that were being used.
Of course! This is why I opened: https://issues.apache.org/jira/browse/LUCENE-8729 As a workaround, I committed: https://github.com/apache/lucene-solr/commit/2a1ed6e4848abc6ab9bce27c170bce28a4c9691c So we can proceed with testing the JDK13 EA builds (especially those of Shipilev with fastdebug, so we can check if Hotspot issues were solved)! Uwe > -- Jon > > On 3/19/19 10:51 AM, Uwe Schindler wrote: > > 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]>; javadoc- > [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/ > >>>>>> > >>>>>>
