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

[Jonathan Gibbons]

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%20summary%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/
>>>>
>>>>