[
https://issues.apache.org/jira/browse/LUCENE-8729?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Uwe Schindler updated LUCENE-8729:
----------------------------------
Attachment: LUCENE-8729-workaround.patch
> 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
> Priority: Major
> Attachments: LUCENE-8729-workaround.patch
>
>
> 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: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
