Skip to content

Commit 145bcb9

Browse files
oshandooshando
committed
Add Javadoc Coverage doclet
1 parent b7b4076 commit 145bcb9

38 files changed

+3815
-0
lines changed

‎javadoc-coverage/.travis.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
language: java
2+
jdk:
3+
- oraclejdk8

‎javadoc-coverage/LICENSE‎

Lines changed: 674 additions & 0 deletions
Large diffs are not rendered by default.

‎javadoc-coverage/NOTICE‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Copyright ${startYear}-${currentYear} ${name}
2+
3+
Licensed under the General Public License Version 3 (the "License");
4+
you may not use this file except in compliance with the License.
5+
You may obtain a copy of the License at
6+
7+
https://www.gnu.org/licenses/gpl-3.0
8+
9+
Unless required by applicable law or agreed to in writing, software
10+
distributed under the License is distributed on an "AS IS" BASIS,
11+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
See the License for the specific language governing permissions and
13+
limitations under the License.

‎javadoc-coverage/README.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# JavaDoc Coverage Doclet
2+
[![Build Status](https://img.shields.io/travis/manoelcampos/javadoc-coverage/master.svg)](https://travis-ci.org/manoelcampos/javadoc-coverage) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/0fef8ada2def4d239931f90a50a3f778)](https://www.codacy.com/app/manoelcampos/javadoc-coverage?utm_source=github.com&utm_medium=referral&utm_content=manoelcampos/javadoc-coverage&utm_campaign=Badge_Grade) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.manoelcampos/javadoc-coverage/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.manoelcampos/javadoc-coverage) [![GPL licensed](https://img.shields.io/badge/license-GPL-blue.svg)](http://www.gnu.org/licenses/gpl-3.0)
3+
4+
![](coverage-report-sample.png)
5+
6+
The Doclet parses java source files and checks the percentage of the Java code covered by JavaDoc documentation, including:
7+
- packages (*Java 9 modules not supported yet*)
8+
- classes, inner classes, interfaces and enums
9+
- class attributes
10+
- methods, parameters, exceptions and return value.
11+
12+
A sample coverage report is available [here](https://manoelcampos.com/javadoc-coverage/sample-project/target/site/apidocs/javadoc-coverage.html).
13+
14+
Current IDEs warn about missing JavaDoc tags and documentation, allowing you to individually fix the issues, but you don't get a big the picture.
15+
Similar to code coverage tools, this plugin provides a way to get a summarized overview of your project's documentation coverage.
16+
It provides a [Doclet](http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/doclet/overview.html) to be used with the JavaDoc Tool to show JavaDoc documentation coverage of your project.
17+
18+
# Usage
19+
20+
The easier ways to use the plugin is through Maven or Gradle. You can use the plugin calling the JavaDoc Tool directly from the command line (but this isn't handy and it isn't explained here).
21+
22+
## Maven: Using the CoverageDoclet in a regular way
23+
24+
To generate the regular JavaDoc HTML files and the coverage report, you have to include two `<execution>` tags for the `maven-javadoc-plugin` inside your project's `pom.xml` file, as the exemple below:
25+
26+
```xml
27+
<build>
28+
<plugins>
29+
<plugin>
30+
<groupId>org.apache.maven.plugins</groupId>
31+
<artifactId>maven-javadoc-plugin</artifactId>
32+
<version>2.10.4</version>
33+
<executions>
34+
<!-- Exports JavaDocs to regular HTML files -->
35+
<execution>
36+
<id>javadoc-html</id>
37+
<phase>package</phase>
38+
<goals>
39+
<goal>javadoc</goal>
40+
</goals>
41+
</execution>
42+
43+
<!-- Generates the JavaDoc coverage report -->
44+
<execution>
45+
<id>javadoc-coverage</id>
46+
<phase>package</phase>
47+
<goals>
48+
<goal>javadoc</goal>
49+
</goals>
50+
<configuration>
51+
<doclet>com.manoelcampos.javadoc.coverage.CoverageDoclet</doclet>
52+
<docletArtifact>
53+
<groupId>com.manoelcampos</groupId>
54+
<artifactId>javadoc-coverage</artifactId>
55+
<version>1.1.0</version>
56+
</docletArtifact>
57+
</configuration>
58+
</execution>
59+
</executions>
60+
</plugin>
61+
<plugins>
62+
<build>
63+
```
64+
65+
Now, to generate the regular JavaDocs in HTML and the documentation coverage report, you can execute the `package` goal in Maven, using your IDE or the command line inside your project's root directory:
66+
67+
```bash
68+
mvn clean package
69+
```
70+
71+
The JavaDoc coverage report is generated by default as `javadoc-coverage.html` at `target/site/apidocs/`.
72+
73+
There is a [sample project](sample-project) where you can test the plugin. Just execute the command above inside the project's directory to see the results.
74+
75+
## Maven: Using the CoverageDoclet with the maven-site-plugin
76+
If you are generating a maven site and want to include the regular JavaDocs HTML and the JavaDoc Coverage Report into the "Reports" section of the site, the `maven-javadoc-plugin` must be included with slightly different configurations into the `<reporting>` tag (instead of the `<build>` tag), as the example below:
77+
78+
```xml
79+
<reporting>
80+
<plugins>
81+
<plugin>
82+
<groupId>org.apache.maven.plugins</groupId>
83+
<artifactId>maven-javadoc-plugin</artifactId>
84+
<version>2.10.4</version>
85+
<reportSets>
86+
<reportSet>
87+
<!-- Exports JavaDocs to regular HTML files -->
88+
<id>javadoc-html</id>
89+
<reports>
90+
<report>javadoc</report>
91+
</reports>
92+
</reportSet>
93+
94+
<reportSet>
95+
<!-- Generates the JavaDoc coverage report -->
96+
<id>javadoc-coverage</id>
97+
<reports>
98+
<report>javadoc</report>
99+
</reports>
100+
<configuration>
101+
<name>JavaDoc Coverage</name>
102+
<description>Percentage of the code coverage by JavaDoc documentation.</description>
103+
<doclet>com.manoelcampos.javadoc.coverage.CoverageDoclet</doclet>
104+
<docletArtifact>
105+
<groupId>com.manoelcampos</groupId>
106+
<artifactId>javadoc-coverage</artifactId>
107+
<version>1.1.0</version>
108+
</docletArtifact>
109+
<!-- This is the same as using -d into the additionalparam tag -->
110+
<destDir>javadoc-coverage</destDir>
111+
<!-- You can also use -o instead of -outputName to define
112+
the name of the generated report. -->
113+
<additionalparam>-outputName "index.html"</additionalparam>
114+
</configuration>
115+
</reportSet>
116+
</reportSets>
117+
</plugin>
118+
</plugins>
119+
</reporting>
120+
```
121+
122+
Notice that in this case, the coverage report is being generated into the `target/site/javadoc-coverage` (as defined by the `destDir` tag) with the name of `index.html` (as defined by the `<additionalparam>` tag), as required for the maven site. More details of additional parameters is provided in the next section.
123+
124+
Now, to generate the site you can execute:
125+
126+
```bash
127+
mvn clean site
128+
```
129+
130+
The list of project's reports will be included into the `target/site/project-reports.html` file.
131+
132+
## Gradle
133+
134+
To use the Doclet with Gradle, add the following code to your `build.gradle` file.
135+
136+
```gradle
137+
configurations {
138+
// Other configuration lines might be in here
139+
javadocCoverage
140+
}
141+
dependencies {
142+
// Your application's other dependencies go here.
143+
javadocCoverage "com.manoelcampos:javadoc-coverage:1.1.0"
144+
}
145+
// This generates the Javadoc coverage report into build/reports/javadoc/javadoc-coverage.html
146+
task javadocCoverageReport(type: Javadoc, dependsOn: javadoc) {
147+
source = sourceSets.main.allJava
148+
destinationDir = reporting.file("javadoc")
149+
options.docletpath = configurations.javadocCoverage.files.asType(List)
150+
options.doclet = "com.manoelcampos.javadoc.coverage.CoverageDoclet"
151+
}
152+
// Optionally you can add the dependsOn here so that when you generate the javadoc
153+
// jar, e.g. if you include the javadocJar in a publishing configuration, the javadoc
154+
// coverage report will be generated automatically.
155+
task javadocJar(type: Jar, dependsOn: javadocCoverageReport) {
156+
classifier "javadoc"
157+
from javadoc.destinationDir
158+
}
159+
```
160+
161+
# Additional Configuration (optional)
162+
163+
You can define additional configurations for the plugin.
164+
The examples below are presented only for Maven (but the same parameters work for Gradle).
165+
166+
## Changing the name of the coverage report file
167+
The CoverageDoclet accepts the command line parameter `-outputName` (`-o` for short) to set the name of the report. The following example shows the code to be added to the `<configuration>` tag of the `maven-javadoc-plugin`:
168+
```xml
169+
<additionalparam>-outputName "my-project-javadoc-coverage-report.html"</additionalparam>
170+
```
171+
172+
## Excluding packages from the coverage report
173+
You can exclude some packages from the coverage report by adding the code example below into the `<configuration>` tag of the `maven-javadoc-plugin`.
174+
175+
```xml
176+
<configuration>
177+
<doclet>com.manoelcampos.javadoc.coverage.CoverageDoclet</doclet>
178+
<docletArtifact>
179+
<groupId>com.manoelcampos</groupId>
180+
<artifactId>javadoc-coverage</artifactId>
181+
<version>1.1.0</version>
182+
</docletArtifact>
183+
<!-- Excludes packages from the coverage report. -->
184+
<excludePackageNames>com.manoelcampos.sample2</excludePackageNames>
185+
</configuration>
186+
```
187+
188+
The example shows how to ignore the package `com.manoelcampos.sample2` from the coverage report. The `<excludePackageNames>` tag accepts a list of packages separated by `:` and also wildcards such as `*`.
189+
For more details, check this [link](https://maven.apache.org/plugins/maven-javadoc-plugin/examples/exclude-package-names.html).
190+
191+
If you are generating the regular JavaDoc HTML files, you have to include this configuration only where the CoverageDoclet is being used into your pom.xml, unless you want these packages to be excluded from the regular JavaDocs too.
192+
193+
# Building the Doclet from Sources
194+
195+
The Doclet is a Java Maven project which can be built directly from any IDE or using the following maven command:
196+
197+
```bash
198+
mvn clean install
199+
```
200+
201+
The command builds the Doclet and install it at your local maven repository.
202+

‎javadoc-coverage/_config.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
theme: jekyll-theme-architect

‎javadoc-coverage/coverage-report-sample.png‎

215 KB
Loading

0 commit comments

Comments
 (0)