Uwe Schindler created LUCENE-8729:
-------------------------------------
Summary: Java 13: Fix Javadocs issues
Key: LUCENE-8729
URL: https://issues.apache.org/jira/browse/LUCENE-8729
Project: Lucene - Core
Issue Type: Bug
Components: general/javadocs
Reporter: Uwe Schindler
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:
{noformat}
[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
{noformat}
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!
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
