[
https://issues.apache.org/jira/browse/MJAVADOC-748?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Adam Gent updated MJAVADOC-748:
-------------------------------
Description:
For a multi module modular project (e.g. a project with multiple module-info
submodules)
I have yet to see a correct usage of {{detectOfflineLinks}}.
Here is the use case I expect most people including myself is when performing
the following
1. Generate non-aggregated javadoc jars for each module for maven central
2. Generate an aggregated exploded javadoc and host it
The hope is in step 1 the cross module links will use step 2 aggregated html.
The idea is someone clicks on a javadoc.io hosted javadoc and then clicks on a
class that is in a separate module the link will not break but takes us to the
aggregate hosted doc.
Here is the problem the detectOfflineLinks does a whole bunch incorrect
heuristics to guess the online URL that do not map at all to the aggregate
javadoc.
In an aggregate javadoc you get a directory of all the module-info modules. I
stress module-info and not maven artifact names.
You can see an example of that here:
https://github.com/jstachio/jstachio.github.io/tree/d036294/p/jstachio/v0.11.0
Now if we go to javadoc.io :
https://javadoc.io/doc/io.jstach/jstachio/0.11.0/io.jstach.jstachio/module-summary.html
And look at JStache link (search in page) it has the following URL:
https://github.com/jstachio/jstachio/jstachio-api-parent/jstachio-annotation/apidocs/io.jstach.jstache/io/jstach/jstache/JStache.html
Now ignoring the whole {{project.url}} (which btw ... why is this is not a
property? Like it really doesn't make since because a project.url is going to
have multiple versions on its page.)
The project.url is: https://github.com/jstachio/jstachio but it should be
https://jstach.io/p/jstachio/v0.11.0 (so for now mentally replace that).
For the JStache link we have
{{jstachio-api-parent/jstachio-annotation/apidocs/io.jstach.jstache/io/jstach/jstache/JStache.html}}.
(BTW the directory {{jstachio-api-parent}} is actually just {{api}} so even if
I just host the built project it still would not work).
The above should be (ignoring project.url prefix):
{{io.jstach.jstache/io/jstach/jstache/JStache.html}}
As the module name is {{io.jstach.jstache}}.
I set this issue as minor because I assume the work around is it manually put
in all the offlineLinks. I haven't tried that but I assume it will work albeit
laborious.
I have serious doubts anyone uses detectOfflineLinks with success. Please show
me an example if I'm wrong. For one it requires doing something like this with
project.url:
{{<url>https://mysite.com/project/${project.version}</url>}}
I have looked around and I don't see the above much.
----
With project.url of https://jstach.io/p/jstachio/v1.0.0-SNAPSHOT:
{{code}}
[DEBUG] Added Javadoc offline link:
https://jstach.io/p/jstachio/v1.0.0-SNAPSHOT/jstachio-api-parent/jstachio-annotation/apidocs
for the module: io.jstach:jstachio-annotation:jar:1.0.0-SNAPSHOT
{{code}}
it should be:
{{code}}
[DEBUG] Added Javadoc offline link:
https://jstach.io/p/jstachio/v1.0.0-SNAPSHOT for the module:
io.jstach:jstachio-annotation:jar:1.0.0-SNAPSHOT
{{code}}
That is the offline link should just be the {{project.url}} and should not have
the module artifact names anywhere in the URL.
I assume this is a happening because the submodules project.url
(project.getUrl()) uses the artifact name including the parent.
https://github.com/apache/maven-javadoc-plugin/blob/931164d0c5d11b4ac4559ada68ee5fba1d0df4f6/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java#L5853
was:
For a multi module modular project (e.g. a project with multiple module-info
submodules)
I have yet to see a correct usage of {{detectOfflineLinks}}.
Here is the use case I expect most people including myself is when performing
the following
1. Generate non-aggregated javadoc jars for each module for maven central
2. Generate an aggregated exploded javadoc and host it
The hope is in step 1 the cross module links will use step 2 aggregated html.
The idea is someone clicks on a javadoc.io hosted javadoc and then clicks on a
class that is in a separate module the link will not break but takes us to the
aggregate hosted doc.
Here is the problem the detectOfflineLinks does a whole bunch incorrect
heuristics to guess the online URL that do not map at all to the aggregate
javadoc.
In an aggregate javadoc you get a directory of all the module-info modules. I
stress module-info and not maven artifact names.
You can see an example of that here:
https://github.com/jstachio/jstachio.github.io/tree/d036294/p/jstachio/v0.11.0
Now if we go to javadoc.io :
https://javadoc.io/doc/io.jstach/jstachio/0.11.0/io.jstach.jstachio/module-summary.html
And look at JStache link (search in page) it has the following URL:
https://github.com/jstachio/jstachio/jstachio-api-parent/jstachio-annotation/apidocs/io.jstach.jstache/io/jstach/jstache/JStache.html
Now ignoring the whole {{project.url}} (which btw ... why is this is not a
property? Like it really doesn't make since because a project.url is going to
have multiple versions on its page.)
The project.url is: https://github.com/jstachio/jstachio
We have
{{jstachio-api-parent/jstachio-annotation/apidocs/io.jstach.jstache/io/jstach/jstache/JStache.html}}.
(BTW the directory {{jstachio-api-parent}} is actually just {{api}} so even if
I just host the built project it still would not work).
The above should be (ignoring project.url prefix):
{{io.jstach.jstache/io/jstach/jstache/JStache.html}}
I set this issue as minor because I assume the work around is it manually put
in all the offlineLinks. I haven't tried that but I assume it will work albeit
laborious.
I have serious doubts anyone uses detectOfflineLinks with success. Please show
me an example if I'm wrong. For one it requires doing something like this with
project.url:
{{<url>https://mysite.com/project/${project.version}</url>}}
I have looked around and I don't see the above much.
> detectOfflineLinks URL generation for modules is not helpful
> ------------------------------------------------------------
>
> Key: MJAVADOC-748
> URL: https://issues.apache.org/jira/browse/MJAVADOC-748
> Project: Maven Javadoc Plugin
> Issue Type: Improvement
> Affects Versions: 3.5.0
> Reporter: Adam Gent
> Priority: Minor
>
> For a multi module modular project (e.g. a project with multiple module-info
> submodules)
> I have yet to see a correct usage of {{detectOfflineLinks}}.
> Here is the use case I expect most people including myself is when performing
> the following
> 1. Generate non-aggregated javadoc jars for each module for maven central
> 2. Generate an aggregated exploded javadoc and host it
> The hope is in step 1 the cross module links will use step 2 aggregated html.
> The idea is someone clicks on a javadoc.io hosted javadoc and then clicks on
> a class that is in a separate module the link will not break but takes us to
> the aggregate hosted doc.
>
> Here is the problem the detectOfflineLinks does a whole bunch incorrect
> heuristics to guess the online URL that do not map at all to the aggregate
> javadoc.
> In an aggregate javadoc you get a directory of all the module-info modules. I
> stress module-info and not maven artifact names.
> You can see an example of that here:
> https://github.com/jstachio/jstachio.github.io/tree/d036294/p/jstachio/v0.11.0
> Now if we go to javadoc.io :
> https://javadoc.io/doc/io.jstach/jstachio/0.11.0/io.jstach.jstachio/module-summary.html
> And look at JStache link (search in page) it has the following URL:
> https://github.com/jstachio/jstachio/jstachio-api-parent/jstachio-annotation/apidocs/io.jstach.jstache/io/jstach/jstache/JStache.html
> Now ignoring the whole {{project.url}} (which btw ... why is this is not a
> property? Like it really doesn't make since because a project.url is going to
> have multiple versions on its page.)
> The project.url is: https://github.com/jstachio/jstachio but it should be
> https://jstach.io/p/jstachio/v0.11.0 (so for now mentally replace that).
> For the JStache link we have
> {{jstachio-api-parent/jstachio-annotation/apidocs/io.jstach.jstache/io/jstach/jstache/JStache.html}}.
> (BTW the directory {{jstachio-api-parent}} is actually just {{api}} so even
> if I just host the built project it still would not work).
> The above should be (ignoring project.url prefix):
> {{io.jstach.jstache/io/jstach/jstache/JStache.html}}
> As the module name is {{io.jstach.jstache}}.
> I set this issue as minor because I assume the work around is it manually put
> in all the offlineLinks. I haven't tried that but I assume it will work
> albeit laborious.
> I have serious doubts anyone uses detectOfflineLinks with success. Please
> show me an example if I'm wrong. For one it requires doing something like
> this with project.url:
> {{<url>https://mysite.com/project/${project.version}</url>}}
> I have looked around and I don't see the above much.
> ----
> With project.url of https://jstach.io/p/jstachio/v1.0.0-SNAPSHOT:
> {{code}}
> [DEBUG] Added Javadoc offline link:
> https://jstach.io/p/jstachio/v1.0.0-SNAPSHOT/jstachio-api-parent/jstachio-annotation/apidocs
> for the module: io.jstach:jstachio-annotation:jar:1.0.0-SNAPSHOT
> {{code}}
> it should be:
> {{code}}
> [DEBUG] Added Javadoc offline link:
> https://jstach.io/p/jstachio/v1.0.0-SNAPSHOT for the module:
> io.jstach:jstachio-annotation:jar:1.0.0-SNAPSHOT
> {{code}}
> That is the offline link should just be the {{project.url}} and should not
> have the module artifact names anywhere in the URL.
> I assume this is a happening because the submodules project.url
> (project.getUrl()) uses the artifact name including the parent.
> https://github.com/apache/maven-javadoc-plugin/blob/931164d0c5d11b4ac4559ada68ee5fba1d0df4f6/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java#L5853
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
