Dawid Weiss created LUCENE-9126:
-----------------------------------
Summary: Javadoc linting options silently swallow documentation
errors
Key: LUCENE-9126
URL: https://issues.apache.org/jira/browse/LUCENE-9126
Project: Lucene - Core
Issue Type: Bug
Reporter: Dawid Weiss
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:
{code}
# Examples below use plain javadoc from Java 11.
cd lucene/core
{code}
This emulates what we have in Ant (this is roughly the options Ant emits):
{code}
javadoc -d build\output -encoding "UTF-8" -sourcepath src\java -subpackages org
-quiet -Xdoclint:all -Xdoclint:-missing -Xdoclint:-accessibility
=> no errors.
{code}
Now rerun it with this syntax:
{code}
javadoc -d build\output -encoding "UTF-8" -sourcepath src\java -subpackages org
-quiet -Xdoclint:all,-missing,-accessibility
=> 100 errors, 5 warnings
{code}
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:
{code}
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
{code}
Let's get rid of html linting:
{code}
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>>)
{code}
Finally, let's get rid of syntax linting:
{code}
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
{code}
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
--
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
