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

Tue Mar 19 18:18:18 UTC 2019

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
> > 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/
> >>>>>>
> >>>>>>