Mark Michaelis created MJAVADOC-827:
---------------------------------------
Summary: addStylesheet Misaligned With stylesheetFile From
Dependencies
Key: MJAVADOC-827
URL: https://issues.apache.org/jira/browse/MJAVADOC-827
Project: Maven Javadoc Plugin
Issue Type: Bug
Components: javadoc
Affects Versions: 3.11.2, 3.3.0
Reporter: Mark Michaelis
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)
