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

Tue Mar 19 18:14:33 UTC 2019

I agree the documentation for doclint needs to be improved.

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.

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