Maven 2.x Javadoc Plugin

includeDependencySources does not handle external dependencies and filters for reactor dependencies correctly

Details

  • Type: Bug Bug
  • Status: Closed Closed
  • Priority: Major Major
  • Resolution: Fixed
  • Affects Version/s: 2.8
  • Fix Version/s: 2.8.1
  • Labels:
    None
  • Testcase included:
    yes
  • Number of attachments :
    4

Description

Setting includeDependencySources=true should include the -sources artifacts of the dependencies of the current project, filtered via dependencySourceIncludes and/or dependencySourceExcludes, in the javadoc generation. However, there are some major issues with the current implementation:

1) filters are ignored for reactor dependencies: Scenario: you have an aggregator project consisting of 3 modules, the 3rd module has a dependency to the first and second one, it has includeDependencySources set to true and explicitly excluded the 2nd module from the javadoc sources via dependencySourceExcludes. If you build the aggregator project, the 2nd module will be included nevertheless (filter does not work), but if you build module 3 only, it works as expected.

2) external dependencies are not added to the javadoc generation: if you have a project which has a dependency which is not part of the current project (e.g. the servlet-api in MyFaces) and you explicitly include it for javadoc generation via dependencySourceIncludes, it won't be included. The problem here is the dependency resolution with a filter: The ArtifactResolver uses the filter to check the whole dependency trail of an artifact (and not just the artifact itself), thus the current project must also be included by the filter or no dependencies of it will be resolved by the ArtifactResolver. However, the current project is not a dependency of the current project, it is the same and thus not explicitly included by dependencySourceIncludes. This means the filter must be modified for dependency resolution to always include the current project artifact.

3) includeTransitiveDependencySources does not work as expected: The name of this property implies that not only the current project's dependencies, but also all transitive dependencies are added for javadoc generation. However, currently this property is only passed on to the PatternIncludesArtifactFilter and/or the PatternExcludesArtifactFilter, which is wrong and actually breaks the include/exclude mechanism if it is set to false (unfortunately the default value).

I will attach an integration test showing the issues described and a patch solving this issue.

  1. Text File
    MJAVADOC-320-fix.patch
    07/Jul/11 10:59 AM
    7 kB
    Jakob Korherr
  2. Text File
    MJAVADOC-320-fix-2.patch
    07/Jul/11 12:52 PM
    11 kB
    Jakob Korherr
  3. Text File
    MJAVADOC-320-integration-test.patch
    07/Jul/11 10:58 AM
    17 kB
    Jakob Korherr
  4. Text File
    MJAVADOC-320-integration-test-2.patch
    07/Jul/11 12:52 PM
    17 kB
    Jakob Korherr

Issue Links

is related to

New Feature - A new feature of the product, which has yet to be developed. MJAVADOC-280 Allow creation of aggregated javadocs source bundles from project dependencies

  • Major - Major loss of function.
  • Closed - The issue is considered finished, the resolution is correct. Issues which are not closed can be reopened.

Activity

Ascending order - Click to sort in descending order
Hide
Permalink
Jakob Korherr added a comment -

integration test showing issues.

Show
Jakob Korherr added a comment - integration test showing issues.
Hide
Permalink
Jakob Korherr added a comment -

fix for MJAVADOC-320

Show
Jakob Korherr added a comment - fix for MJAVADOC-320
Hide
Permalink
Jakob Korherr added a comment -

add link to issue introducing includeDependencySources property.

Show
Jakob Korherr added a comment - add link to issue introducing includeDependencySources property.
Hide
Permalink
Jakob Korherr added a comment -

BTW this issue blocks us in moving MyFaces core from the dependency-plugin with recompilation to the shade-plugin.

Show
Jakob Korherr added a comment - BTW this issue blocks us in moving MyFaces core from the dependency-plugin with recompilation to the shade-plugin.
Hide
Permalink
Jakob Korherr added a comment -

updated patches:

fix-2.patch now also fixes includeTransitiveDependencySources correctly

integration-test-2.patch removes 2.8.1-SNAPSHOT with @pom.version@

Show
Jakob Korherr added a comment - updated patches: fix-2.patch now also fixes includeTransitiveDependencySources correctly integration-test-2.patch removes 2.8.1-SNAPSHOT with @pom.version@
Hide
Permalink
Mark Struberg added a comment -

patch reviewed, tested and applied.

Thanks Jakob!

Show
Mark Struberg added a comment - patch reviewed, tested and applied. Thanks Jakob!
Hide
Permalink
Guram Savinov added a comment - - edited

Hi.

I try to use plugin ver.2.8 in multi-module project.

In parent POM I add plugin config:

  <build>
    ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.8</version>
        <configuration>
          <includeDependencySources>true</includeDependencySources>
          <dependencySourceIncludes>
            <dependencySourceInclude>org.springframework.security:*</dependencySourceInclude>
          </dependencySourceIncludes>
        </configuration>
      </plugin>
    ...
  </build>

When creating javadoc I want to auto downloading dependency sources and add it to the '-source' key of the javadoc utility.
In this project I just need 'org.springframework.security:*' artifacts sources.

It's two questions appears:

1. In result javadocs it isn't javadocs from dependency sources, in this project from org.springframework.security artifacts sources.
Is it problem is issue #2 of the MJAVADOC-320, and it will be fixed in the 2.8.1 release?

2. If I execute 'mvn clean javadoc:aggregate' in the parent module of my project, building seems like without problems, but if I call in parent module 'mvn clean javadoc:javadoc', building put this:

Downloading: http://repo1.maven.org/maven2/org/atinject/inject-tck/1.0.0-PFD-3-jboss-1/inject-tck-1.0.0-PFD-3-jboss-1.pom
[INFO] Unable to find resource 'org.atinject:inject-tck:pom:1.0.0-PFD-3-jboss-1' in repository central (http://repo1.maven.org/maven2)
Downloading: http://repo1.maven.org/maven2/org/springframework/security/spring-security-core/3.0.7.RELEASE/spring-security-core-3.0.7.RELEASE-javadoc-resources.jar
Downloading: http://repo1.maven.org/maven2/joda-time/joda-time/2.0/joda-time-2.0-javadoc-resources.jar
Downloading: http://repo1.maven.org/maven2/org/atinject/inject-tck/1.0.0-PFD-3-jboss-1/inject-tck-1.0.0-PFD-3-jboss-1.jar
Downloading: http://repo1.maven.org/maven2/commons-logging/commons-logging/1.1.1/commons-logging-1.1.1-javadoc-resources.jar
Downloading: http://repo1.maven.org/maven2/aopalliance/aopalliance/1.0/aopalliance-1.0-javadoc-resources.jar
[INFO] Unable to find resource 'joda-time:joda-time:jar:javadoc-resources:2.0' in repository central (http://repo1.maven.org/maven2)
Downloading: http://repo1.maven.org/maven2/org/aspectj/aspectjrt/1.6.8/aspectjrt-1.6.8-javadoc-resources.jar
[INFO] Unable to find resource 'org.springframework.security:spring-security-core:jar:javadoc-resources:3.0.7.RELEASE' in repository central (http://repo1.maven.org/maven2)
Downloading: http://repo1.maven.org/maven2/org/springframework/spring-expression/3.0.6.RELEASE/spring-expression-3.0.6.RELEASE-javadoc-resources.jar
[INFO] Unable to find resource 'org.atinject:inject-tck:jar:1.0.0-PFD-3-jboss-1' in repository central (http://repo1.maven.org/maven2)
[INFO] Unable to find resource 'commons-logging:commons-logging:jar:javadoc-resources:1.1.1' in repository central (http://repo1.maven.org/maven2)
[INFO] Unable to find resource 'aopalliance:aopalliance:jar:javadoc-resources:1.0' in repository central (http://repo1.maven.org/maven2)
[INFO] Unable to find resource 'org.aspectj:aspectjrt:jar:javadoc-resources:1.6.8' in repository central (http://repo1.maven.org/maven2)
Downloading: http://repo1.maven.org/maven2/org/aspectj/aspectjweaver/1.6.8/aspectjweaver-1.6.8-javadoc-resources.jar
[INFO] Unable to find resource 'org.springframework:spring-expression:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http://repo1.maven.org/maven2)
Downloading: http://repo1.maven.org/maven2/org/springframework/spring-core/3.0.6.RELEASE/spring-core-3.0.6.RELEASE-javadoc-resources.jar
[INFO] Unable to find resource 'org.aspectj:aspectjweaver:jar:javadoc-resources:1.6.8' in repository central (http://repo1.maven.org/maven2)
[INFO] Unable to find resource 'org.springframework:spring-core:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http://repo1.maven.org/maven2)
Downloading: http://repo1.maven.org/maven2/org/springframework/spring-asm/3.0.6.RELEASE/spring-asm-3.0.6.RELEASE-javadoc-resources.jar
[INFO] Unable to find resource 'org.springframework:spring-asm:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http://repo1.maven.org/maven2)
Downloading: http://repo1.maven.org/maven2/org/springframework/spring-context/3.0.6.RELEASE/spring-context-3.0.6.RELEASE-javadoc-resources.jar
[INFO] Unable to find resource 'org.springframework:spring-context:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http://repo1.maven.org/maven2)
Downloading: http://repo1.maven.org/maven2/org/springframework/spring-aop/3.0.6.RELEASE/spring-aop-3.0.6.RELEASE-javadoc-resources.jar
[INFO] Unable to find resource 'org.springframework:spring-aop:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http://repo1.maven.org/maven2)
Downloading: http://repo1.maven.org/maven2/org/springframework/spring-beans/3.0.6.RELEASE/spring-beans-3.0.6.RELEASE-javadoc-resources.jar
[INFO] Unable to find resource 'org.springframework:spring-beans:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http://repo1.maven.org/maven2)
Downloading: http://repo1.maven.org/maven2/org/springframework/spring-tx/3.0.6.RELEASE/spring-tx-3.0.6.RELEASE-javadoc-resources.jar
[INFO] Unable to find resource 'org.springframework:spring-tx:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http://repo1.maven.org/maven2)
[INFO]

What is it, why this dependencies appears, is it plugin dependencies?
Why this output isn't appears when I call 'mvn clean javadoc:aggregate'?
This messages appears every time when I call 'mvn clean javadoc:javadoc'.

Show
Guram Savinov added a comment - - edited Hi. I try to use plugin ver.2.8 in multi-module project. In parent POM I add plugin config: <build> ... <plugin> <groupId> org.apache.maven.plugins </groupId> <artifactId> maven-javadoc-plugin </artifactId> <version> 2.8 </version> <configuration> <includeDependencySources> true </includeDependencySources> <dependencySourceIncludes> <dependencySourceInclude> org.springframework.security:* </dependencySourceInclude> </dependencySourceIncludes> </configuration> </plugin> ... </build> When creating javadoc I want to auto downloading dependency sources and add it to the '-source' key of the javadoc utility. In this project I just need 'org.springframework.security:*' artifacts sources. It's two questions appears: 1. In result javadocs it isn't javadocs from dependency sources, in this project from org.springframework.security artifacts sources. Is it problem is issue #2 of the MJAVADOC-320 , and it will be fixed in the 2.8.1 release? 2. If I execute 'mvn clean javadoc:aggregate' in the parent module of my project, building seems like without problems, but if I call in parent module 'mvn clean javadoc:javadoc', building put this: Downloading: http: //repo1.maven.org/maven2/org/atinject/inject-tck/1.0.0-PFD-3-jboss-1/inject-tck-1.0.0-PFD-3-jboss-1.pom [INFO] Unable to find resource 'org.atinject:inject-tck:pom:1.0.0-PFD-3-jboss-1' in repository central (http: //repo1.maven.org/maven2) Downloading: http: //repo1.maven.org/maven2/org/springframework/security/spring-security-core/3.0.7.RELEASE/spring-security-core-3.0.7.RELEASE-javadoc-resources.jar Downloading: http: //repo1.maven.org/maven2/joda-time/joda-time/2.0/joda-time-2.0-javadoc-resources.jar Downloading: http: //repo1.maven.org/maven2/org/atinject/inject-tck/1.0.0-PFD-3-jboss-1/inject-tck-1.0.0-PFD-3-jboss-1.jar Downloading: http: //repo1.maven.org/maven2/commons-logging/commons-logging/1.1.1/commons-logging-1.1.1-javadoc-resources.jar Downloading: http: //repo1.maven.org/maven2/aopalliance/aopalliance/1.0/aopalliance-1.0-javadoc-resources.jar [INFO] Unable to find resource 'joda-time:joda-time:jar:javadoc-resources:2.0' in repository central (http: //repo1.maven.org/maven2) Downloading: http: //repo1.maven.org/maven2/org/aspectj/aspectjrt/1.6.8/aspectjrt-1.6.8-javadoc-resources.jar [INFO] Unable to find resource 'org.springframework.security:spring-security-core:jar:javadoc-resources:3.0.7.RELEASE' in repository central (http: //repo1.maven.org/maven2) Downloading: http: //repo1.maven.org/maven2/org/springframework/spring-expression/3.0.6.RELEASE/spring-expression-3.0.6.RELEASE-javadoc-resources.jar [INFO] Unable to find resource 'org.atinject:inject-tck:jar:1.0.0-PFD-3-jboss-1' in repository central (http: //repo1.maven.org/maven2) [INFO] Unable to find resource 'commons-logging:commons-logging:jar:javadoc-resources:1.1.1' in repository central (http: //repo1.maven.org/maven2) [INFO] Unable to find resource 'aopalliance:aopalliance:jar:javadoc-resources:1.0' in repository central (http: //repo1.maven.org/maven2) [INFO] Unable to find resource 'org.aspectj:aspectjrt:jar:javadoc-resources:1.6.8' in repository central (http: //repo1.maven.org/maven2) Downloading: http: //repo1.maven.org/maven2/org/aspectj/aspectjweaver/1.6.8/aspectjweaver-1.6.8-javadoc-resources.jar [INFO] Unable to find resource 'org.springframework:spring-expression:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http: //repo1.maven.org/maven2) Downloading: http: //repo1.maven.org/maven2/org/springframework/spring-core/3.0.6.RELEASE/spring-core-3.0.6.RELEASE-javadoc-resources.jar [INFO] Unable to find resource 'org.aspectj:aspectjweaver:jar:javadoc-resources:1.6.8' in repository central (http: //repo1.maven.org/maven2) [INFO] Unable to find resource 'org.springframework:spring-core:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http: //repo1.maven.org/maven2) Downloading: http: //repo1.maven.org/maven2/org/springframework/spring-asm/3.0.6.RELEASE/spring-asm-3.0.6.RELEASE-javadoc-resources.jar [INFO] Unable to find resource 'org.springframework:spring-asm:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http: //repo1.maven.org/maven2) Downloading: http: //repo1.maven.org/maven2/org/springframework/spring-context/3.0.6.RELEASE/spring-context-3.0.6.RELEASE-javadoc-resources.jar [INFO] Unable to find resource 'org.springframework:spring-context:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http: //repo1.maven.org/maven2) Downloading: http: //repo1.maven.org/maven2/org/springframework/spring-aop/3.0.6.RELEASE/spring-aop-3.0.6.RELEASE-javadoc-resources.jar [INFO] Unable to find resource 'org.springframework:spring-aop:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http: //repo1.maven.org/maven2) Downloading: http: //repo1.maven.org/maven2/org/springframework/spring-beans/3.0.6.RELEASE/spring-beans-3.0.6.RELEASE-javadoc-resources.jar [INFO] Unable to find resource 'org.springframework:spring-beans:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http: //repo1.maven.org/maven2) Downloading: http: //repo1.maven.org/maven2/org/springframework/spring-tx/3.0.6.RELEASE/spring-tx-3.0.6.RELEASE-javadoc-resources.jar [INFO] Unable to find resource 'org.springframework:spring-tx:jar:javadoc-resources:3.0.6.RELEASE' in repository central (http: //repo1.maven.org/maven2) [INFO] What is it, why this dependencies appears, is it plugin dependencies? Why this output isn't appears when I call 'mvn clean javadoc:aggregate'? This messages appears every time when I call 'mvn clean javadoc:javadoc'.

People

  • Assignee:
    Mark Struberg
    Reporter:
    Jakob Korherr
Vote (0)
Watch (2)

Dates

  • Created:
    Updated:
    Resolved: