Aggregating Javadocs from Dependency Sources

[Jason Voegele]

I am trying to generate Javadocs for a project that is conceptually an
aggregate of several other projects. I am using the information from
this page as a guide:
http://maven.apache.org/plugins/maven-javadoc-plugin/examples/aggregate-dependency-sources.html


That page indicates that you can use the includeDependencySources option
to have the Javadoc plugin download the source JARs for dependencies and
include them in the sources against which Javadocs are generated.
However, I am unable to get it to work. The Javadoc plugin does indeed
recognize this option, which I can ascertain by the fact that if source
JARs for any dependencies are not available it fails with an error.

I have tried using both dependencySourceExcludes and
dependencySourceIncludes, but no matter how I craft these options the
Javadocs for dependencies are never included. When I execute mvn
javadoc:jar, for example, I receive a bunch of messages on the terminal
indicating that Maven is trying to download javadoc resources but source
JARs for dependencies are not downloaded and the generate Javadoc does
not include dependency sources.

Here is how I have configured the Javadoc plugin in my POM:

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.7</version>
<configuration>
<includeDependencySources>true</includeDependencySources>

<includeTransitiveDependencySources>false</includeTransitiveDependencySources>
<dependencySourceIncludes>

<dependencySourceInclude>org.terracotta.toolkit:*</dependencySourceInclude>
</dependencySourceIncludes>

</configuration>
</plugin>


I've attached the complete POM for your perusal, in case you might find
that information helpful, and the output of the mvn javadoc:jar command
is also available here: http://paste.ubuntu.com/432246/

Is this a bug in the Javadoc plugin, or am I somehow using it
incorrectly?

Thanks for any help you can provide.

[Benson Margulies]

There is something of a best practice of avoiding the aggregation
feature of the javadoc plugin, in favor of:

1) create source artifacts for each dependency
2) use dependency plugin to unpack the source artifacts into 'one big tree'
3) run the javadoc plugin on the result tree to produce aggregate javadoc.

This is used at Apache CXF, amongst other places.

Post by Jason Voegele
I am trying to generate Javadocs for a project that is conceptually an
aggregate of several other projects. I am using the information from
http://maven.apache.org/plugins/maven-javadoc-plugin/examples/aggregate-dependency-sources.html
That page indicates that you can use the includeDependencySources option
to have the Javadoc plugin download the source JARs for dependencies and
include them in the sources against which Javadocs are generated.
However, I am unable to get it to work.  The Javadoc plugin does indeed
recognize this option, which I can ascertain by the fact that if source
JARs for any dependencies are not available it fails with an error.
I have tried using both dependencySourceExcludes and
dependencySourceIncludes, but no matter how I craft these options the
Javadocs for dependencies are never included.  When I execute mvn
javadoc:jar, for example, I receive a bunch of messages on the terminal
indicating that Maven is trying to download javadoc resources but source
JARs for dependencies are not downloaded and the generate Javadoc does
not include dependency sources.
 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-javadoc-plugin</artifactId>
   <version>2.7</version>
   <configuration>
       <includeDependencySources>true</includeDependencySources>
<includeTransitiveDependencySources>false</includeTransitiveDependencySources>
       <dependencySourceIncludes>
<dependencySourceInclude>org.terracotta.toolkit:*</dependencySourceInclude>
       </dependencySourceIncludes>
   </configuration>
 </plugin>
I've attached the complete POM for your perusal, in case you might find
that information helpful, and the output of the mvn javadoc:jar command
is also available here: http://paste.ubuntu.com/432246/
Is this a bug in the Javadoc plugin, or am I somehow using it
incorrectly?
Thanks for any help you can provide.
--
Jason Voegele
No matter who you are, some scholar can show you the great idea you had
was had by someone before you.
---------------------------------------------------------------------

[Jason Voegele]

Post by Benson Margulies
There is something of a best practice of avoiding the aggregation
1) create source artifacts for each dependency
2) use dependency plugin to unpack the source artifacts into 'one big tree'
3) run the javadoc plugin on the result tree to produce aggregate javadoc.
This is used at Apache CXF, amongst other places.

Thank you, Benson. This approach seems to work just fine.

[bedge]

Is this best practice of avoiding the javadoc:aggregate target still the
case?

I find it a bit surprising as I've been combing the web for solutions to
javadoc aggregation problems and this is the first I've heard of such a
convention.
There is also no mention of this in the maven docs.

In any case, I concur with the OP that the
includeDependencySources/excludeDependencySources is truly broken.

--
View this message in context: http://maven.40175.n5.nabble.com/Aggregating-Javadocs-from-Dependency-Sources-tp126034p5522496.html
Sent from the Maven - Users mailing list archive at Nabble.com.