[
https://issues.apache.org/jira/browse/LUCENE-9242?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17048696#comment-17048696
]
Tomoko Uchida edited comment on LUCENE-9242 at 3/1/20 10:37 PM:
----------------------------------------------------------------
I opened a draft PR [https://github.com/apache/lucene-solr/pull/1304]. This
adds a gradle task, named {{invokeJavadoc}}, which generates Javadocs with
inter-module hyperlinks by invoking Ant javadoc task. Also this passes
{{checkMissingJavadocs}} check.
The task can be called as below:
{code:java}
# generate javadocs for each project
$ ./gradlew :lucene:core:invokeJavadoc
{code}
or,
{code:java}
# generate javadocs for all projects at once
$ ./gradlew invokeJavadoc
{code}
The work isn't completed yet, but the most important parts are already ported.
Quick replies to comments on LUCENE-9201 will be following:
{quote}It is my personal preference to have a project-scope granularity. This
way you can run project-scoped task (like gradlew -p lucene/core javadoc). My
personal take on assembling "distributions" is to have a separate project that
just takes what it needs from other projects and puts it together (with any
tweaks required). This makes it easier to reason about how a distribution is
assembled and from where, while each project just takes care of itself.
{quote}
I'd love this approach, however, when I was trying I noticed that it looks
difficult to properly generate inter-module hyperlinks without affecting the
existing javadoc's path hierarchy (already published on the apache.org web
site), if we want to place generated javadocs under
${sub_project_root}/build/docs/javadoc (gradle's default javadoc destination).
The fundamental problem here I think is, in order to make hyperlinks from a
module A to another module B, we need to know the effective relative path from
module A to module B and pass it to the Javadoc Tool.
I aggregated all javadocs into {{lucene/build/docs}} or {{solr/build/docs}},
just as the Ant build does, to resolve the relative paths. I might miss
something - please let me know if my understanding isn't correct.
{quote}for "directly call the javadoc tool" we may want to use the ant task as
a start. This ant task is doing quite a bit of work above and beyond what the
tool is doing (if you look at the relevant code to ant, you may be shocked!).
{quote}
As the first step I tried to reproduce the principal Ant macros :
"invoke-javadoc" (in lucene/common-build.xml) and "invoke-module-javadoc" (in
lucene/module-build.xml) on gradle build. By doing so, there's now no missing
package summaries and inter-module links will be generated. (Current setups to
resolve the hyperlinks look quite redundant, I think we can do it in more
sophisticated ways.)
{quote}A custom javadoc invocation is certainly possible and could possibly
make things easier in the long run.
{quote}
{quote}as a second step you can look at computing package list for a module
yourself (it may allow invoking the tool directly).
{quote}
Yes we will probably be able to throw away all ant tasks and only rely on pure
gradle code. Some extra effort will be needed to faithfully transfer the
elaborate ant setups into corresponding gradle scripts...
{quote}You'd need to declare inputs/ outputs properly though so that it is
skippable. Those javadoc invocations take a long time in precommit.
{quote}
I passed inputs/outputs to the task not to needlessly repeat the javadoc
invocation. It seems to work - {{ant.javadoc}} is called only when the java
source or output directory is changed.
was (Author: tomoko uchida):
I opened a draft PR [https://github.com/apache/lucene-solr/pull/1304]. This
adds a gradle task, named {{invokeJavadoc}}, which generates Javadocs with
inter-module hyperlinks by invoking Ant javadoc task. Also this passes
{{checkMissingJavadocs}} check.
The task can be called as below:
{code:java}
# generate javadocs for each project
$ ./gradlew :lucene:core:invokeJavadoc
{code}
or,
{code:java}
# generate javadocs for all projects at once
$ ./gradlew invokeJavadoc
{code}
The work isn't completed yet, but the most important parts are already ported.
Quick replies to comments on LUCENE-9201 will be following:
{quote}It is my personal preference to have a project-scope granularity. This
way you can run project-scoped task (like gradlew -p lucene/core javadoc). My
personal take on assembling "distributions" is to have a separate project that
just takes what it needs from other projects and puts it together (with any
tweaks required). This makes it easier to reason about how a distribution is
assembled and from where, while each project just takes care of itself.
{quote}
I'd love this approach, however, when I was trying I noticed that it looks
difficult to properly generate inter-module hyperlinks without affecting the
existing javadoc's path hierarchy (already published on the apache.org web
site), if we want to place generated javadocs under
${sub_project_root}/build/docs/javadoc (gradle's default javadoc destination).
The fundamental problem here I think is, in order to make hyperlinks from a
module A to another module B, we need to know the effective relative path from
module A to module B and pass it to the Javadoc Tool.
I aggregated all javadocs into {{lucene/build/docs}} or {{solr/build/docs}},
just as the Ant build does, to resolve the relative paths. I might miss
something - please let me know if my understanding isn't correct.
{quote}for "directly call the javadoc tool" we may want to use the ant task as
a start. This ant task is doing quite a bit of work above and beyond what the
tool is doing (if you look at the relevant code to ant, you may be shocked!).
{quote}
As the first step I tried to reproduce the principal Ant macros :
"invoke-javadoc" (in lucene/common-build.xml) and "invoke-module-javadoc" (in
lucene/module-build.xml) on gradle build. By doing so, there's now no missing
package summaries and inter-module links will be generated. (Current setups to
resolve the hyper links looks quite redundant, I think we can do it more
sophisticated ways.)
{quote}A custom javadoc invocation is certainly possible and could possibly
make things easier in the long run.
{quote}
{quote}as a second step you can look at computing package list for a module
yourself (it may allow invoking the tool directly).
{quote}
Yes we will probably be able to throw away all ant tasks and only rely on pure
gradle code. Some extra effort will be needed to faithfully transfer the
elaborate ant setups into corresponding gradle scripts...
{quote}You'd need to declare inputs/ outputs properly though so that it is
skippable. Those javadoc invocations take a long time in precommit.
{quote}
I passed inputs/outputs to the task not to needlessly repeat the javadoc
invocation. It seems to work - {{ant.javadoc}} is called only when the java
source or output directory is changed.
> Gradle Javadoc task should output the same documents as Ant
> -----------------------------------------------------------
>
> Key: LUCENE-9242
> URL: https://issues.apache.org/jira/browse/LUCENE-9242
> Project: Lucene - Core
> Issue Type: Sub-task
> Components: general/javadocs
> Affects Versions: master (9.0)
> Reporter: Tomoko Uchida
> Priority: Major
> Time Spent: 10m
> Remaining Estimate: 0h
>
> "javadoc" task for the Gradle build does not correctly output package
> summaries, since it ignores "package.html" file in the source tree (so the
> Python linter {{checkJavaDocs.py}} detects that and fails for now.)
> Also the "javadoc" task should make inter-module links just as Ant build does.
> See for more details: LUCENE-9201
--
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
