[ 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)