Java - Adding references to Framework API Documentation (docs) while generating Javadocs

In continuation to my earlier posts about using Maven to generate Javadocs for your project source code, I want to provide some inputs on how you can link your project's generated apiDocs to the apiDocs of the framework it is dependent on. In my case, I was working on an ATG project and used Maven javadoc plugin to generate javadocs for my project source code, the apiDocs got generated successfully but all the ATG Framework classes that my project source code referred to were linked to the Oracle java documentation. This was because the javadoc plugin assumes that any class thats not defined in the project source code is actually a java class. To avoid this from happening, you can add links/link tag combination (as given in the snippet below) and point the same to the folder/URL which contains the apiDocs/package-list (in my case this file was inside the folder mentioned in the link tag) file. This file helps the javadoc utility understand as to which packages are covered by the docs provided by the folder in the link tag. This way if your project is referring to multiple frameworks you can download the framework documentation to a folder and add the offline links to the javadoc plugin configuration section and rerun the maven command to regenerate the apiDocs with the updated links.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.8</version>
    <configuration>
        <reportOutputDirectory>C:/Project/apiDocs</reportOutputDirectory>
        <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
        <docletArtifact>
            <groupId>org.umlgraph</groupId>
            <artifactId>doclet</artifactId>
            <version>5.1</version>
        </docletArtifact>
        <additionalparam>-views</additionalparam>
        <useStandardDocletOptions>true</useStandardDocletOptions>
        <links>
            <link>file:///C:/Users/nseshadr/Downloads/E22630_01/Platform.1002/apidoc</link>
        </links>
    </configuration>
    <executions>
        <execution>
            <id>aggregate</id>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

You can always refer to the Maven Javadoc Plugin page for more information and options.

Note: Also you can download the Oracle Sun Java API documentation and add information about the same to the links/link section and that will make all your java class references point to the local API folder as against the internet URL. 

Java - Generating code coverage reports using Cobertura with Maven

If you have a requirement or a plan to generate test code coverage reports for your project using Cobertura and you are using Maven as your build tool, copy the following onto your pom.xml in the build/plugins section.

<plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>cobertura-maven-plugin</artifactId>
      <version>2.5.1</version>
       <configuration>
      <instrumentation>
        <includes>
          <include>com/company/**/*Manage*.class</include>
          <include>com/company/**/*Tool*.class</include>
        </includes>
      </instrumentation>
      <aggregate>true</aggregate>
      <outputDirectory>C:/Project/TestCoverageReports</outputDirectory>
    </configuration>
    <executions>
      <execution>
          <phase>package</phase>
          <goals>
              <goal>cobertura</goal>
          </goals>
      </execution>
    </executions>
</plugin>

Make sure that your maven doesnt skip tests - i.e., -Dmaven.test.skip is set to false.

Note that the test coverage report will be generated in the configured outputDirectory. If you are working on a project that has a parent POM which invokes multiple child POMs, add this to the parent POM, the aggregate option will generate one code coverage report for all the set of modules invoked from inside the parent without any changes to the child POMs. You can always refer to the Maven Cobertura Plugin page for more information and options.

Java - Generating javadocs for your source code with Maven using Custom Doclet (GraphViz)

Its always good to have a visual representation rather than a text based representation for us to understand things better. This concept works well for the javadocs that we generate as well. As mentioned in one of my other blogs - Software Tools - I managed to use GraphViz and UmlGraph to generate javadocs with ClassDiagrams. You can also automate this by integrating all this into your Maven POM.

So if you are using Maven as the build tool on your project and you want to generate javadocs for all your source files with the UML classdiagram embedded on them, please add the following to your POM inside the build/plugins section.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.8</version>
    <configuration>
        <reportOutputDirectory>C:/Project/apiDocs</reportOutputDirectory>
        <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
        <docletArtifact>
            <groupId>org.umlgraph</groupId>
            <artifactId>doclet</artifactId>
            <version>5.1</version>
        </docletArtifact>
        <additionalparam>-views</additionalparam>
        <useStandardDocletOptions>true</useStandardDocletOptions>
    </configuration>
    <executions>
        <execution>
            <id>aggregate</id>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

As mentioned in my other post on javadoc generation using Maven please make necessary changes to your mvn command. Also make sure you download GraphViz, install the same and add its bin folder to the PATH environment variable before running the mvn command or executing the script that runs the mvn command otherwise you would see issues about "dot" not being recognized as a commnd or some error of that kind.

Java - Generating javadocs for your source code with Maven

If you have a requirement or a plan to generate javadocs for your project source code and you are using Maven as your build tool, copy the following onto your pom.xml in the build/plugins section.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.8</version>
    <configuration>
        <reportOutputDirectory>C:/Project/apiDocs</reportOutputDirectory>
    </configuration>
    <executions>
        <execution>
        <id>aggregate</id>
        <goals>
            <goal>aggregate</goal>
        </goals>
        </execution>
    </executions>
</plugin>

Also dont forget to add javadoc:aggregate to the mvn goal/tasks list for the javadocs to get generated. 

mvn -e -s application\settings.xml -Denvironment=development -Dmaven.test.skip=false clean install javadoc:aggregate

Note that the javadocs will be generated in the configured reportOutputDirectory. If you are working on a project that has a parent POM which invokes multiple child POMs, add this to the parent POM, the aggregate option will generate one javadoc for all the set of modules invoked from inside the parent without any changes to the child POMs. You can always refer to the Maven Javadoc Plugin page for more information and options.