How to Use the javadoc plug-in to generate documents for multi-module Maven Projects

Requirement

Recently, you have to generate a JavaDoc document for a Maven project with the following project structure.

Project
| -- Pom. xml
| -- Module1
| '-- Pom. xml
| -- Module2
| '-- Pom. xml
| -- Module3
| -- Pom. xml

This requires the javadoc Maven plug-in to be proposed in this article.

Basic usage

The basic configuration of the plug-in is simple:

<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-javadoc-plugin</artifactId><version>2.9.1</version></plugin>

For a common Maven project, this configuration allows you to output a JavaDoc document (using the javadoc: javadoc command ).

Multi-module Maven Project

Now we are a multi-module Maven project, so we need some additional configuration to complete this operation:

<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-javadoc-plugin</artifactId><version>2.9.1</version><configuration>        <aggregate>true</aggregate></configuration></plugin>

If an aggregate is set to true, You can generate the javadoc of the sub-module under the target of the parent project when you run javadoc: JavaDoc in the parent project, and it will be integrated into a JavaDoc.

Custom tag

Now the question is:

The method annotations in our class are as follows:

/*** @ Author: James * @ group: group * @ Date: 21:14:49 * @ Comments: The ejb interface for adding, deleting, modifying, and querying operations contained in the page * @ Version: 1.0.0 */public interface IOperationBean {/*** @ MethodName: getOperationByID * @ Description: obtain the Operation contained in the page by Id * @ param ID the operation ID contained in the page */PageOperation getOperationByID (String ID );}

After the JavaDoc is generated, we do not see the corresponding content in the Description and MethodName annotations. This leads to missing descriptions of methods.

After the experiment, you need to add a comment like this to keep the method description behind the method name as jdk does:

/*** Obtain the Operation contained in the page by Id * @ param ID the operation ID contained in the page */PageOperation getOperationByID (String ID );

After the end of the project, let's make a few changes. I checked the official website and found that there are custom tags, which exactly solves this problem.

This problem is due to the fact that we are not familiar with JavaDoc generation.

Let's just look at the example:

<Plugin> <groupId> org. apache. maven. plugins </groupId> <artifactId> maven-javadoc-plugin </artifactId> <version> 2.9.1 </version> <configuration> <aggregate> true </aggregate> <tags> <tag> <name> Description </name> <placement> a </placement> 

Note:

1. name is the name of the annotation in your Java code.
2. There are eight placement types on the official website. I also tried it myself. In fact, this means that you should put the annotations (methods, fields, and classes) on JavaDoc.

3. head. If this is not written, the name is used. If it is written, the result is as follows:



In this way, you can define your own annotation specifications and generate corresponding JavaDoc documents.
The custom path function is generally not used. Just take a look at it and write it down.

Here, I need to read a few words about the conventions that are better than the configuration. When I first used Maven, I saw this. Can I set the Maven directory like this? Yes, you can change it.

It can only be said that we do not need to change this in most cases, but it does not mean that we can stop this operation when doing so for users and future maintenance, is not a good choice.

Now, let's take a look at the settings:


<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-javadoc-plugin</artifactId><version>2.9.1</version><configuration>        <reportOutputDirectory>../myoutput</reportOutputDirectory>        <destDir>myapidocs</destDir></configuration></plugin>

Note:

1. reportOutputDirectory indicates the path

2. destDir refers to the target folder. Here, problems encountered in the process of generating javadoc documents using the JavaDoc plug-in Maven multi-module are all solved.