[LUCENE-8729] Java 13: Fix Javadocs (accessibility) issues

• Type: Bug
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 9.0
• Component/s: general/javadocs
• Lucene Fields: New
• Assignee: Unassigned
• Reporter: Uwe Schindler
• Created: 18/Mar/19 10:19
• Updated: 28/Aug/22 15:43
• Resolved: 08/Feb/20 15:04

Description

On Policeman Jenkins I isntalled a preview release of JDK 13. The Oracle supplied one does not yet have the issue, but nightly builds of Alexej Shipilev contain a patch that does additional check on Javadocs comments when doclint is enabled, so the next OpenJDK builds of Oracle will likely have the same issue. It fails already in "javac". The output is: https://jenkins.thetaphi.de/job/Lucene-Solr-8.x-Linux/275/consoleText

Problem is HTML headings (like "H1" inside javadocs comments clashing with "H1" generated by Javadoc output, or "H3" without "H2"), in JDK-11 there is already a comment in the Javadocs spec (https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html, "When writing documentation comments for members, it is best not to use HTML heading tags such as <h1> and <h2>, because the standard doclet creates an entire structured document, and these structural tags might interfere with the formatting of the generated document.".

The error is the following:

    [mkdir] Created dir: /home/jenkins/workspace/Lucene-Solr-8.x-Linux/lucene/build/core/classes/java
    [javac] Compiling 868 source files to /home/jenkins/workspace/Lucene-Solr-8.x-Linux/lucene/build/core/classes/java
    [javac] /home/jenkins/workspace/Lucene-Solr-8.x-Linux/lucene/core/src/java/org/apache/lucene/codecs/blocktree/BlockTreeTermsWriter.java:98: error: heading used out of sequence: <H3>, compared to implicit preceding heading: <H1>
    [javac]  * <h3>Term Dictionary</h3>
    [javac]    ^
    [javac] /home/jenkins/workspace/Lucene-Solr-8.x-Linux/lucene/core/src/java/org/apache/lucene/codecs/lucene80/package-info.java:21: error: unexpected heading used: <H1>, compared to implicit preceding heading: <H1>
    [javac]  * <h1>Apache Lucene - Index File Formats</h1>
    [javac]    ^
    [javac] /home/jenkins/workspace/Lucene-Solr-8.x-Linux/lucene/core/src/java/org/apache/lucene/index/PointValues.java:41: error: unexpected heading used: <H1>, compared to implicit preceding heading: <H1>
    [javac]  * <h1>Basic Point Types</h1>
    [javac]    ^
    [javac] /home/jenkins/workspace/Lucene-Solr-8.x-Linux/lucene/core/src/java/org/apache/lucene/index/PointValues.java:68: error: unexpected heading used: <H1>, compared to implicit preceding heading: <H1>
    [javac]  * <h1>Geospatial Point Types</h1>
    [javac]    ^
    [javac] /home/jenkins/workspace/Lucene-Solr-8.x-Linux/lucene/core/src/java/org/apache/lucene/index/PointValues.java:78: error: unexpected heading used: <H1>, compared to implicit preceding heading: <H1>
    [javac]  * <h1>Advanced usage</h1>
    [javac]    ^
    [javac] /home/jenkins/workspace/Lucene-Solr-8.x-Linux/lucene/core/src/java/org/apache/lucene/search/Sort.java:37: error: heading used out of sequence: <H3>, compared to implicit preceding heading: <H1>
    [javac]  * <h3>Valid Types of Values</h3>
    [javac]    ^
    [javac] /home/jenkins/workspace/Lucene-Solr-8.x-Linux/lucene/core/src/java/org/apache/lucene/util/packed/package-info.java:34: error: heading used out of sequence: <H3>, compared to implicit preceding heading: <H1>
    [javac]  * <h3>In-memory structures</h3>
    [javac]    ^
    [javac] Note: Some input files use or override a deprecated API.
    [javac] Note: Recompile with -Xlint:deprecation for details.
    [javac] 7 errors

I think we should fix this and maybe don't use headings at all (as suggested in the Spec), or fix them to be at lease correct. Some hints to issues in latest JDK docs: https://bugs.openjdk.java.net/browse/JDK-8220379

Not sure about doclint in general, I'l ask on maing lists, how this affects 3rd party code!