[
https://issues.apache.org/jira/browse/LUCENE-8729?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17032906#comment-17032906
]
Robert Muir commented on LUCENE-8729:
-------------------------------------
I am working on it. The problems are mostly caused by horrible style issues
with larger headings in the old javadocs format. It would make font size so
absurdly big that people would use the wrong heading level. But trunk only
generates html5 javadocs, so we can fix it. the checker makes it trivial.
> Java 13: Fix Javadocs (accessibility) 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
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
