[
https://issues.apache.org/jira/browse/MJAVADOC-827?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17958209#comment-17958209
]
Olivier Lamy commented on MJAVADOC-827:
---------------------------------------
This project has moved from Jira to GitHub Issues. This issue was migrated to
[apache/maven-javadoc-plugin#1202|https://github.com/apache/maven-javadoc-plugin/issues/1202].
Please visit the GitHub issue to view further activity, add comments, or
subscribe to receive notifications.
> addStylesheet Misaligned With stylesheetFile From Dependencies
> --------------------------------------------------------------
>
> Key: MJAVADOC-827
> URL: https://issues.apache.org/jira/browse/MJAVADOC-827
> Project: Maven Javadoc Plugin (Moved to GitHub Issues)
> Issue Type: Bug
> Components: javadoc
> Affects Versions: 3.3.0, 3.11.2
> Reporter: Mark Michaelis
> Priority: Major
>
> In MJAVADOC-625 support for {{--add-stylesheet}} has been introduced as new
> configuration parameter {{{}<addStylesheets>{}}}. The code has some issues
> though with several side effects compared to {{<stylesheetFile>}} refering to
> a resource in a dependency.
> h2. First Issue: Javadoc writes to src/main/javadoc
> Given a snippet configuration snippet like this:
>
> {code:java}
> <stylesheetfile>from-dependeny.css</stylesheetfile>
> <addStylesheets>
> <addStylesheet>in-src-main-javadoc.css</addStylesheet>
> </addStylesheets>
> {code}
> If Javadoc is generated, it writes the content of {{from-dependeny.css}} to
> {{{}src/main/javadoc{}}}.
>
> This is caused by the check that should ensure, that {{<addStylesheets>}} is
> only used with an existing {{{}<stylesheetFile>{}}}.
> h2. Second Issue: Additional Stylesheets Not Read From Dependencies
> Unlike {{{}<stylesheetFile>{}}}, files given in {{<addStylesheets>}} are not
> taken from dependencies which was expected by us.
> Thus, the assumption would be, that this should work (now using the default
> stylesheet, not overriding {{{}<stylesheetFile>{}}}):
>
> {code:java}
> <addStylesheets>
> <addStylesheet>additional-from-dependency.css</addStylesheet>
> </addStylesheets> {code}
> This does won't work, because the corresponding code only respects the
> Javadoc-folder, thus {{src/main/javadoc}} and not any other – including
> resources provided by dependencies.
>
> h2. The Cause
> The cause is located around these lines:
> *
> [maven-javadoc-plugin/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java
> at maven-javadoc-plugin-3.11.2 ·
> apache/maven-javadoc-plugin|https://github.com/apache/maven-javadoc-plugin/blob/maven-javadoc-plugin-3.11.2/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java#L2762-L2820]
> First, {{getAddStylesheet}} does not get the {{javadocOutputDirectory}} as
> the parameter suggests, but instead {{{}getJavadocDirectory(){}}}.
> *First Issue:* This causes the subsequent check for the main stylesheet file
> to exist to write to {{src/main/javadoc}} (due to the internal call to
> {{{}getResource(){}}}).
> *Second Issue:* Unlike {{{}getStylesheetFile(){}}}, {{getAddStylesheet()
> }}does not invoke {{getResource()}} if a stylesheet file cannot be found.
> Instead, it just fails with an exception.
> *Kind of third issue (design scope):* While {{getStylesheetFile()}} just
> complains, that files do not exist (but does not fail),
> {{getAddStylesheet()}} always fails, when a file does not exist. When fixing
> this issue, it needs to be decided, if this contract should be kept as is, or
> if we just forward to {{getResource()}} as final fallback without raising an
> extra exception.
> Regarding the very similar approach, both behaviors should be aligned here,
> so that I would vote for skipping the exception and leave it at a warning
> instead.
> h2. Workaround
> There are several workarounds, like first unpacking resources via dependency
> plugin. I preferred using {{<resourceArtifacts>}} and subsequent
> {{<additionalOptions>}} to bypass the invalid check in
> {{{}getAddStylesheet(){}}}:
> {code:java}
> <configuration>
> <resourcesArtifacts>
> <resourcesArtifact>
> <groupId>com.mycompany</groupId>
> <artifactId>common-javadoc-resources</artifactId>
> <version>${project.version}</version>
> </resourcesArtifact>
> </resourcesArtifacts>
> <additionalOptions>
> <additionalOption>--add-stylesheet</additionalOption>
> <additionalOption>additional-from-dependency.css</additionalOption>
> </additionalOptions>
> </configuration>{code}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
