Adam Gent created MJAVADOC-748:
----------------------------------
Summary: 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
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.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
