You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by jd...@apache.org on 2010/04/12 23:25:55 UTC
svn commit: r933420 -
/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate-dependency-sources.apt.vm
Author: jdcasey
Date: Mon Apr 12 21:25:55 2010
New Revision: 933420
URL: http://svn.apache.org/viewvc?rev=933420&view=rev
Log:
[MJAVADOC-280] Adding documentation
Added:
maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate-dependency-sources.apt.vm (with props)
Added: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate-dependency-sources.apt.vm
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate-dependency-sources.apt.vm?rev=933420&view=auto
==============================================================================
--- maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate-dependency-sources.apt.vm (added)
+++ maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate-dependency-sources.apt.vm Mon Apr 12 21:25:55 2010
@@ -0,0 +1,246 @@
+ ------
+ Aggregating Javadocs from Dependency Sources
+ ------
+ John Casey
+ ------
+ 2010-04-12
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Aggregating Javadocs from Dependency Sources
+
+ <<Since: 2.6.2>>
+
+ Consider the following project dependency graph:
+
++-----+
+
+org.test:project-distro:0.1
+ |
+ |--> org.test.dep:project-A:1.0
+ | |
+ | |--> commons-lang:commons-lang:1.0
+ | |
+ | `--> commons-io:commons-io:1.0
+ |
+ |--> org.test.dep:project-B:1.1
+ | |
+ | `--> commons-io:commons-io:1.0
+ |
+ |--> org.test.dep:project-C:1.0
+ |
+ `--> commons-cli:commons-cli:1.0
+
++-----+
+
+ Suppose you maintain a series of projects with separate release cycles, along with another project which serves to
+ integrate everything together to provide a tested platform, with its dependencies coordinated for compatibility. In
+ order to produce the <<<project-distro>>> distribution, you'll want to produce a comprehensive set of javadocs
+ containing not only what little code is in the distro project itself - which isn't likely to be very enlightening -
+ but also the javadocs for your other projects, which are dependencies of the distribution.
+
+ Since version <2.6.2> of the maven-javadoc-plugin, you can do this using the <<<includeDependencySources>>> flag and
+ its associated configuration options. Using this flag, it's possible to aggregate sources from other modules in a
+ multi-module build <or> use the <<<sources>>> and <<<test-sources>>> jars published alongside the main artifacts for
+ your projects. It's also possible to fine-tune which dependencies' sources should be aggregated, and which ignored.
+ Last but not least, it's possible to include non-source javadoc configurations and resources from your dependencies by
+ publishing <<<javadoc-resources>>> and <<<test-javadoc-resources>>> bundle artifacts alongside your dependencies'
+ main artifacts.
+
+ To get started, let's look at how to lay the ground work for dependency-driven javadoc aggregation.
+
+* Preparing Dependencies for Aggregation
+
+ Dependency-driven javadoc aggregation works by resolving the sources for included dependencies, then including these
+ sources in the javadoc production process for your project. As is common practice with Maven, dependency sources will
+ be resolved from other modules in the current reactor if they are available there. Otherwise, the plugin will attempt
+ to resolve the appropriate sources artifact for the dependency: <<<sources>>> for main javadocs, <<<test-sources>>> for
+ test javadocs. <<NOTE: If your configuration includes a dependency but that dependency's source artifact is unavailable, the
+ javadoc plugin will fail.>>
+
+ The recommended method for producing these source artifacts is the {{{http://maven.apache.org/plugins/maven-source-plugin/}maven-source-plugin}}.
+ The following simple example shows how to produce source artifacts:
+
++-----+
+<project>
+ [...]
+ <groupId>org.test.dep</groupId>
+ <artifactId>project-A</artifactId>
+ <version>1.0</version>
+ [...]
+ <build>
+ <plugins>
+ [...]
+ <plugin>
+ <artifactId>maven-source-plugin</artifactId>
+ <version>2.1.1</version>
+ <executions>
+ <execution>
+ <id>bundle-sources</id>
+ <phase>package</phase>
+ <goals>
+ <!-- produce source artifact for main project sources -->
+ <goal>jar</goal>
+
+ <!-- produce source artifact for project test sources -->
+ <goal>test-jar</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
++-----+
+
+ <<NOTE: If you don't intend to generate test javadocs that include dependency sources, you can omit the
+ <<<test-jar>>> goal above.>>
+
+ At this point, your project is ready to produce the artifacts necessary to support dependency-driven javadoc aggregation.
+ The next time you install or deploy the project, the appropriate artifacts will be available for your distribution
+ project to consume.
+
+* Fine-Tuning Included Dependencies
+
+ Unifying the javadocs of your project and its dependencies is fine, but let's not go too far. Along with your own
+ upstream projects, your distribution may include dependencies on external projects. It may not be appropriate to
+ include javadocs for these projects in your distribution; linking to them is usually better. In any case, you may
+ not have enough influence over these external projects to get them to produce source artifacts like the ones discussed
+ above. In our original example, take a look at that last direct dependency:
+
++-----+
+
+ `--> commons-cli:commons-cli:1.0
+
++-----+
+
+ This is a pretty common direct dependency for projects that provide command-line execution options. But consider
+ what happens if commons-cli doesn't provide a <<<sources>>> jar: dependency-driven javadoc aggregation would fail
+ for any project that contained commons-cli as a direct dependency. To avoid this case, you have the option to fine-tune
+ which dependencies get included in the javadoc aggregation process. In your distribution project, add configuraiton
+ for the <<<maven-javadoc-plugin>>> similar to the following:
+
++-----+
+<project>
+ [...]
+ <groupId>org.test</groupId>
+ <artifactId>project-distro</artifactId>
+ [...]
+ <build>
+ <plugins>
+ [...]
+ <plugin>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>@pom.version@</version>
+ <executions>
+ <execution>
+ <id>javadoc-jar</id>
+ <phase>package</phase>
+ <goals>
+ <goal>jar</goal>
+ </goals>
+ <configuration>
+ <!-- switch on dependency-driven aggregation -->
+ <includeDependencySources>true</includeDependencySources>
+
+ <dependencySourceExcludes>
+ <!-- exclude ONLY commons-cli artifacts -->
+ <dependencySourceExclude>commons-cli:*</dependencySourceExclude>
+ </dependencySourceExcludes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
++-----+
+
+ <<NOTE:>> The above configuration excludes <<only>> commons-cli. If you have multiple external dependencies, it may be easier
+ to configure which dependencies are <<included>>, as follows:
+
++-----+
+ [...]
+ <configuration>
+ <!-- switch on dependency-driven aggregation -->
+ <includeDependencySources>true</includeDependencySources>
+
+ <dependencySourceIncludes>
+ <!-- include ONLY dependencies I control -->
+ <dependencySourceInclude>org.test.dep:*</dependencySourceInclude>
+ </dependencySourceIncludes>
+ </configuration>
+ [...]
++-----+
+
+* Including Javadoc Resources from Dependencies
+
+ Many projects choose customize their javadoc configuration beyond the defaults.
+
+ If you have customized configuration for generating the javadocs in these dependency projects,
+ you may wish to propagate these customizations to the distribution project itself. To do this, use the <<<resource-bundle>>>
+ and <<<test-resource-bundle>>> goals, new in version <<2.6.2>> of the javadoc plugin. These will create new artifacts
+ that contain the javadoc configuration options plus the contents of $\{javadocDirectory} (which defaults to src/main/javadoc),
+ or $\{tetsJavadocDirectory} (which defaults to src/test/javadoc) depending on the bundle goal. If these artifacts are
+ available, the dependency-driven aggregation process will include the content and configuration they contain when
+ generating the javadocs for your distribution. The following example shows how to produce these artifacts:
+
++-----+
+<project>
+ [...]
+ <groupId>org.test.dep</groupId>
+ <artifactId>project-A</artifactId>
+ <version>1.0</version>
+ [...]
+ <build>
+ <plugins>
+ [...]
+ <plugin>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>@pom.version@</version>
+ <executions>
+ <execution>
+ <id>resource-bundles</id>
+ <phase>package</phase>
+ <goals>
+ <!-- produce source artifact for main project sources -->
+ <goal>resource-bundle</goal>
+
+ <!-- produce source artifact for project test sources -->
+ <goal>test-resource-bundle</goal>
+ </goals>
+ <configuration>
+ <detectOfflineLinks>false</detectOfflineLinks>
+ [...]
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ [...]
+</project>
++-----+
+
+ <<NOTE: Again, if you don't need to generate test javadocs, you can omit the <<<test-resource-bundle>>> goal above.>>
+ <<NOTE 2: The configuration option <<<detectOfflineLinks>>> is provided as an example only. It is not required.>>>
Propchange: maven/plugins/trunk/maven-javadoc-plugin/src/site/apt/examples/aggregate-dependency-sources.apt.vm
------------------------------------------------------------------------------
svn:eol-style = native