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

Source: Internet
Author: User

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.

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: info-contact@alibabacloud.com and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.