Maven Javadoc Plugin
  1. Maven Javadoc Plugin
  2. MJAVADOC-320

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. MJAVADOC-320-fix.patch
        7 kB
        Jakob Korherr
      2. MJAVADOC-320-fix-2.patch
        11 kB
        Jakob Korherr
      3. MJAVADOC-320-integration-test.patch
        17 kB
        Jakob Korherr
      4. MJAVADOC-320-integration-test-2.patch
        17 kB
        Jakob Korherr

        Issue Links

          Activity

          Hide
          Jakob Korherr added a comment -

          integration test showing issues.

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

          fix for MJAVADOC-320

          Show
          Jakob Korherr added a comment - fix for MJAVADOC-320
          Hide
          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
          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
          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
          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
          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
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: