You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "Adam Gent (Jira)" <ji...@apache.org> on 2023/03/21 17:19:00 UTC
[jira] [Updated] (MJAVADOC-748) detectOfflineLinks URL generation for modules is not helpful
[ 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)