Maven Reporting Plugins

This section details how to run the plugins and access the reports.

Installing the JavaDoc

The JavaDoc documentation for the API describes all of the CDK classes in detail. The latest version is available here.

Before creating the JavaDoc you will need to install the CDK build util project in your local maven repo.

# install cdk-build-util
$ git clone https://github.com/cdk/cdk-build-util && cd cdk-build-util && mvn install
$ mvn javadoc:aggregate
$ open target/site/apidocs/index.html

PMD

PMD analyses code style (e.g. variable naming, complexity) and reports potential bugs. Currently only production (non-test) code is inspected. The following snippet shows how to run PMD on the 'cdk-silent' module.

cdk/: cd base/silent
cdk/base/silent: ls
cdk/base/silent: mvn pmd:pmd
cdk/base/silent: open target/site/pmd.html 

java-formatter

As a relatively mature project with many different developers there are many different formatting styles used in the CDK source code. Following patches from different IDEs with different settings some files have gotten pretty messy. The java-formatter tidies up the code using consistent settings.

The formatting settings are in the cdk-build-util project cdk-build-util/.../cdk-formatting-conventions.xml.

To run the formatter on the silent module

cdk/: cd base/silent
cdk/base/silent: ls
cdk/base/silent: mvn java-formatter:format
[INFO] --- maven-java-formatter-plugin:0.4:format (default-cli) @ cdk-silent ---
[INFO] Using 'UTF-8' encoding to format source files.
[INFO] Number of files to be formatted: 76
[INFO] Successfully formatted: 76 file(s)
[INFO] Fail to format        : 0 file(s)
[INFO] Skipped               : 0 file(s)
[INFO] Approximate time taken: 3s

JaCoCo

JaCoCo is a tool for analysing test coverage. JaCoCo installs agent instrumentation and check exactly which code lines are hit and missed by tests. This not only serves as a quality measure but also can guide optimisation, "why isn't that conditional ever hit by my tests, is it even possible?".

cdk/: cd base/silent
cdk/base/silent: mvn jacoco:prepare-agent test jacoco:report
cdk/base/silent: open target/site/jacoco/index.html

The contribute method determines the number of pi electrons for an element with specified valence (v) and connectivity (x). We can see that two lines are flagged as yellow. On inspection we can see that 1 of 4 branches was missed. There are four branches because of two conditionals (2^2=4) and one of them is missed.

You can run single tests as follows:

cdk/base/silent: mvn jacoco:prepare-agent test jacoco:report -Dtest=AtomContainerTest

Some IDEs and CI servers are able to integrate the JaCoCo reports directly.

Reporting coverage when the tests are separate to the production code is a little more tricky but possible. Here is an example for the 'cdk-standard' module.

cdk/: cd base/standard
cdk/base/standard: mvn install
cdk/base/standard: cd ../test-standard
cdk/base/test-standard: mvn jacoco:prepare-agent test
cdk/base/standard: cd ../standard
cdk/base/standard: mvn jacoco:report
cdk/base/standard: open target/site/jacoco/index.html

Dependency Tree

Maven can create a dependency tree with the following command:

cdk/: mvn dependency:tree