[
http://jira.codehaus.org/browse/MJAVADOC-95?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=132914#action_132914
]
Stuart R. Jefferys commented on MJAVADOC-95:
--------------------------------------------
After years of using other tools, I am a recent Maven convert. However, I am
also confused by this. I hope this posting to a closed issue will show up
somewhere...
I understand the use of {{jarOutputDirectory}} as an independent configuration
issue, because it is based around a different mojo and life-cycle phase. I
don't understand how the other two directories differ. I assume they are all
real separate locations and not just aliases.
I can't come up with a single use case that would require two copies of the
non-packaged java docs laying around, unless the javadoc tool reuses previously
generated documentation in the same way that a compiler caches previous build
results. If that is not true, then this seems to be an implementation detail,
the difference between what is specifically used as an option for the
underlying javadoc tool ({{-d outputDirectory}}) and where the javadoc should
_really_ end up when generated. If so, do both directories need to be exposed?
Whatever reason the different directories exist for, (to support file-reuse,
implementation hooks, or for backward-compatibility), clear documentation would
help. It is only through documentation of conventions that less-adept users
(such as I) can hope to follow the valuable Maven philosophy of "There may be
more than one way to do it, but lets agree to use the same way unless it really
matters"
> Confusing <reportOutputDirectory> and <outputDirectory> configuration options
> -----------------------------------------------------------------------------
>
> Key: MJAVADOC-95
> URL: http://jira.codehaus.org/browse/MJAVADOC-95
> Project: Maven 2.x Javadoc Plugin
> Issue Type: Wish
> Affects Versions: 2.1
> Reporter: Dmitry Katsubo
> Assignee: Vincent Siveton
> Priority: Minor
> Fix For: 2.3
>
>
> There are two confoguration options, which are a bit confusing:
> * {{<reportOutputDirectory>}} used by {{mvn javadoc:javadoc}}
> * {{<outputDirectory>}} used by {{mvn javadoc:jar}}
> Can they get an equal meaning and usage? Please, concider the
> [multiproject|http://maven.apache.org/plugins/maven-eclipse-plugin/reactor.html]
> configuration example below. The aim is to generate javadoc HTML and jar as
> follows:
> {noformat}
> my-project
> +- docs
> +- javadoc
> | +- my-lib-1.0
> | | +- index.html
> | | ...
> | +- my-lib-api-1.0
> | | +- index.html
> | | ...
> | +- my-lib-1.0-javadoc.jar
> | +- my-lib-api-1.0-javadoc.jar
> ...
> my-lib
> +- src
> | +- java
> +- target
> |
> ...
> my-lib-api
> +- src
> | +- java
> +- target
> |
> ...
> {noformat}
> I am using the following configuration in {{my-project/pom.xml}}:
> {code:xml}
> <build>
> <plugins>
> <plugin>
> <inherited>true</inherited>
> <groupId>org.apache.maven.plugins</groupId>
> <artifactId>maven-javadoc-plugin</artifactId>
> <configuration>
> <!-- Confusing: -->
>
> <reportOutputDirectory>../my-project/docs/javadoc/${project.artifactId}-${project.version}</reportOutputDirectory>
>
> <outputDirectory>../my-project/docs/javadoc/${project.artifactId}-${project.version}</outputDirectory>
> <jarOutputDirectory>../my-project/docs/javadoc</jarOutputDirectory>
> <source>1.5</source>
> <notimestamp>true</notimestamp>
> <linksourcetab>4</linksourcetab>
> </configuration>
> </plugin>
> </plugins>
> </build>
> <modules>
> <module>../my-lib</module>
> <module>../my-lib-api</module>
> </modules>
> {code}
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://jira.codehaus.org/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
