[
https://issues.apache.org/jira/browse/MJAVADOC-560?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781176#comment-17781176
]
Alexander Kriegisch edited comment on MJAVADOC-560 at 10/31/23 1:07 AM:
------------------------------------------------------------------------
Thanks to all of you who commented before me, trying to get to to the bottom of
this. It was quite instructive to read those comments.
Wow, that is really subtle and was not understandable for me when reading the
docs:
* {{javadoc:javadoc}} puts the javadocs into {{target/site/apidocs}} by
default, but
* {{javadoc:jar}} puts them into {{target/apidocs}}.
I really thought, that they would always end up in {{target/apidocs}} when
using the mojo stand-alone and in {{target/site/apidocs}} when creating a Maven
site only. I even modeled my own plugin after this assumption, reading the
Maven Javadoc documentation as a template. Actually, I am disappointed that the
real behaviour is different. I think, it would have made sense if a stand-alone
mojo report has another structure and output directory than a collection of
reports like a Maven site. But of course, that is arguable.
When changing any behaviour and documentation for plugin version 4 and Doxia 2,
please do not forget that for many years, users will still continue to use the
current version in their existing projects, shying away from upgrading many
dependencies, which, as I have experienced, can be a quite non-trivial
challenge in case of Doxia 2. Therefore, I plead for more precise documentation
in the currently maintained version, too.
was (Author: kriegaex):
Thanks to all of you who commented before me, trying to get to to the bottom of
this. It was quite instructive to read those comments.
Wow, that is really subtle and was not understandable for me when reading the
docs:
* {{javadoc:javadoc}} puts the javadocs into {{target/site/apidocs}} by
default, but
* {{javadoc:jar}} puths them into {{target/apidocs}}.
I really thought, that they would always end up in {{target/apidocs}} when
using the mojo stand-alone and in {{target/site/apidocs}} when creating a Maven
site only. I even modeled my own plugin after this assumption, reading the
Maven Javadoc documentation as a template. Actually, I am disappointed that the
real behaviour is different. I think,it would have made sense if a stand-alone
mojo report has another structure and output directory than a collection of
reports like a Maven site. But of course, that is arguable.
When changing any behaviour and documentation for plugin version 4 and Doxia 2,
please do not forget that for many years, users will also use the current
version in their existing projects. Therefore, I plead for more precise
documentation in the currently maintained version, too.
> Clarify outputDirectory, reportOutputDirectory in javadoc:javadoc
> documentation
> -------------------------------------------------------------------------------
>
> Key: MJAVADOC-560
> URL: https://issues.apache.org/jira/browse/MJAVADOC-560
> Project: Maven Javadoc Plugin
> Issue Type: Bug
> Components: javadoc
> Affects Versions: 3.1.0
> Reporter: Gili
> Assignee: Michael Osipov
> Priority: Major
> Fix For: 4.0.0
>
>
> Looking at the documentation for javadoc:javadoc at
> [https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html] I
> see three problems:
> # The documentation lists both *outputDirectory* and *reportOutputDirectory*
> parameters, having the same description. It's not clear what each one is used
> for or what happens if one property is changed without the other.
> # The default value of *outputDirectory* is listed as
> *${project.build.directory}/apidocs* but the value that is actually used is
> *${project.reporting.outputDirectory}/apidocs* (the value of
> *reportOutputDirectory*).
> # It was extremely difficult to find any documentation on
> *${project.reporting.outputDirectory}***, such as what its default value is.
> I eventually found [https://maven.apache.org/pom.html#Reporting] but Google
> does not link directly to this page/section because it doesn't contain an
> explicit reference to *${project.reporting}*.
> Suggested fix(es):
> # Drop one of the two parameters, ideally *reportOutputDirectory*, to avoid
> confusion.
> # Update the documentation so it lists the correct default value for
> *outputDirectory*.
> # Link directly from mention of *${project.reporting.outputDirectory}* to
> [https://maven.apache.org/pom.html#Reporting]
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
