[
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:05 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}} 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.
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)
