[LUCENE-9126] Javadoc linting options silently swallow documentation errors

• Type: Bug
• Status: Closed
• Priority: Minor
• Resolution: Workaround
• Fix Version/s: 9.0
• Lucene Fields: New
• Assignee: Dawid Weiss
• Reporter: Dawid Weiss
• Created: 10/Jan/20 15:04
• Updated: 28/Aug/22 15:55
• Resolved: 27/Aug/20 15:01

Description

I tried to compile javadocs in gradle and I couldn't do it... The output was full of errors.

I eventually narrowed the problem down to lint options – how they are interpreted and parsed just doesn't make any sense to me. Try this:

# Examples below use plain javadoc from Java 11.
cd lucene/core

This emulates what we have in Ant (this is roughly the options Ant emits):

javadoc -d build\output -encoding "UTF-8" -sourcepath src\java -subpackages org -quiet -Xdoclint:all -Xdoclint:-missing -Xdoclint:-accessibility
=> no errors.

Now rerun it with this syntax:

javadoc -d build\output -encoding "UTF-8" -sourcepath src\java -subpackages org -quiet -Xdoclint:all,-missing,-accessibility
=> 100 errors, 5 warnings

This time javadoc displays errors about undefined tags (unknown tag: lucene.experimental), HTML warnings (warning: empty <big> tag), etc.

Let's add our custom tags and add overview file:

javadoc -overview "src/java/overview.html" -tag "lucene.experimental:a:xxx" -tag "lucene.internal:a:xxx" -tag "lucene.spi:t:xxx" -d build\output -encoding "UTF-8" -sourcepath src\java -subpackages org -quiet -Xdoclint:all,-missing,-accessibility
=> 100 errors, 5 warnings
=> still HTML warnings

Let's get rid of html linting:

javadoc -overview "src/java/overview.html" -tag "lucene.experimental:a:xxx" -tag "lucene.internal:a:xxx" -tag "lucene.spi:t:xxx" -d build\output -encoding "UTF-8" -sourcepath src\java -subpackages org -quiet -Xdoclint:all,-missing,-accessibility,-html
=> 3 errors
=> malformed HTML syntax in overview.html: src\java\overview.html:150: error: bad use of '>' (<blockquote><tt>>)

Finally, let's get rid of syntax linting:

javadoc -overview "src/java/overview.html" -tag "lucene.experimental:a:xxx" -tag "lucene.internal:a:xxx" -tag "lucene.spi:t:xxx" -d build\output -encoding "UTF-8" -sourcepath src\java -subpackages org -quiet -Xdoclint:all,-missing,-accessibility,-html,-syntax
=> passes

There are definitely bugs in our documentation – look at the extra ">" in the overview file, for example:
https://github.com/apache/lucene-solr/blob/master/lucene/core/src/java/overview.html#L150

What I can't understand is why the first syntax suppresses pretty much ALL the errors, including missing custom tag definitions. This should work, given what's written in [1]?

[1] https://docs.oracle.com/en/java/javase/11/tools/javadoc.html

Issue Links

• is related to: LUCENE-9131 Correct HTML5 linting errors in javadocs