[
https://issues.apache.org/jira/browse/LUCENE-9201?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17032100#comment-17032100
]
Robert Muir commented on LUCENE-9201:
-------------------------------------
{quote}
Package summary: "ant documentation" uses "package.html" as package summary
description, but "gradlew javadoc" ignores "package.html" (so some packages
lacks summary description in "package-summary.html" when building javadocs by
Gradle). We might be able to make Gradle Javadoc task to properly handle
"package.html" files with some options. Or, should we replace all
"package.html" with "package-info.java" at this time?
{quote}
It is a stupid complex issue. The problem here also exists in the ant build.
The underlying issue is that java 8 produced HTML4 by default. Java 9+ is doing
HTML5. Java 9+ is generating HTML5 even though its manual page implies that
HTML4 is still the default. This kind of shit makes our build too complicated.
Possibly in branch 8.x we can simply pass "-html4" option to javadoc processor
so that it always generates html4 output, even if you happen to use java
9,10,11,12,13,etc to invoke it. Currently if you use java 9+ on this branch,
javadocs are messed up, you get no overview.html, etc. Forcing html4 for this
branch seems like the best way. I will investigate for sure.
On the other hand with master branch things are easier: java 11 is a minimum
requirement, so let's not fight the defaults (which is HTML5). Maybe I am wrong
here, if we change our minds we can just revert my commits and wire in HTML4. I
fixed the syntax issues already in LUCENE-9209. We must get the overviews
working again, so I am not sure if {{package-info.java}} is the best solution
(it addresses package.html, but what about overview.html?)
Sorry for the long answer, but at least it is no mystery.
> Port documentation-lint task to Gradle build
> --------------------------------------------
>
> Key: LUCENE-9201
> URL: https://issues.apache.org/jira/browse/LUCENE-9201
> Project: Lucene - Core
> Issue Type: Sub-task
> Affects Versions: master (9.0)
> Reporter: Tomoko Uchida
> Assignee: Tomoko Uchida
> Priority: Major
> Time Spent: 10m
> Remaining Estimate: 0h
>
> Ant build's "documentation-lint" target consists of those two sub targets.
> * "-ecj-javadoc-lint" (Javadoc linting by ECJ)
> * "-documentation-lint"(Missing javadocs / broken links check by python
> scripts)
--
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
