[
https://issues.apache.org/jira/browse/LUCENE-9126?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Dawid Weiss reassigned LUCENE-9126:
-----------------------------------
Assignee: Dawid Weiss
> 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
> Assignee: Dawid Weiss
> Priority: Major
>
> 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
