多模块Maven项目怎样使用javadoc插件生成文档

需求

近期要对一个项目结构例如以下的Maven项目生成JavaDoc文档。

Project

                        |-- pom.xml

                        |-- Module1

                                |   `-- pom.xml

                        |-- Module2

                                |   `-- pom.xml

                        |-- Module3

                                |-- pom.xml

这个就须要用到本文将要提出的一个Maven插件:javadoc。

基本使用

插件的基本配置非常easy:

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

假设对于一个普通的Maven项目,那么这个配置就能够让你输出一个JavaDoc文档了(使用javadoc:javadoc命令)。

多模块Maven项目

而我们如今是一个多模块的Maven项目,那么就须要一些额外的配置来完毕此操作:

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

就是一个aggregate设置为true,就能够让你在父项目执行javadoc:javadoc的时候,就会将子模块的JavaDoc生成在父项目的target下,而且会将其整合成一个JavaDoc。

自己定义标签

如今问题来了:

我们的类中的方法凝视例如以下

/**
* @author : 张三
* @group : group
* @Date : 2014-01-26 21:14:49
* @Comments : 页面所含操作增删改查的ejb接口
* @Version : 1.0.0
*/
public interface IOperationBean {
/**
* @MethodName : getOperationByID
* @Description : 依据Id获得页面所含操作
* @param ID 页面所含操作ID
*/
PageOperation getOperationByID(String ID);
}

而我们在生成JavaDoc后,并没有看到Description和MethodName这两个注解中相应的内容。也就导致了方法的说明不翼而飞了。

经过实验,要想像jdk那样让方法的描写叙述紧跟在方法名后面,是须要这样加入凝视的:

/**
* 依据Id获得页面所含操作
* @param ID 页面所含操作ID
*/
PageOperation getOperationByID(String ID);

已经到了项目后期。如今再让大家去改这些有些说只是去,查了下官网,发现有自己定义标签。正好解决的就是这种问题。

而这次问题的出现。还是源于我们对于JavaDoc生成不熟悉。

废话不多说,直接看样例:

<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>
<head>用途</head>
</tag>
</tags>
</configuration>
</plugin>

说明:

1.name为你Java代码中的注解的名字

2. placement这个在官网上有8种,我也自己试了下。事实上这个就是说你要把哪些(方法、字段、类)上面的注解放到JavaDoc中

3.head。假设不写这个,用的就是name,假设写了,那么显示效果例如以下:

多模块Maven项目怎样使用javadoc插件生成文档

这样。你就既能够定义自己的凝视规范。又能够生成对应的JavaDoc文档了

自己定义路径

 
      这个功能一般不会用到,仅仅是顺便看了一下。就写下来吧。
 
      在这里须要叨念两句关于约定优于配置,在最初我用Maven的时候,就看到过这种话,Maven文件夹能够不这样设置么?能够,你能够自己改。
 
      仅仅能说我们在大部分时候,是不须要改这个,但不意味着我们在做的时候就能够把这个做死,这样于用户,于今后的维护来说,都不是一个好的选择。
 
      两句叨念完了,如今来看怎么设置吧:
<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>

说明:

 
      1.reportOutputDirectory是说的路径
 
      2.destDir是说的目标目录
 
      
 
      到这里Maven多模块下使用javadoc插件生成JavaDoc文档过程中遇到的问题就都攻克了。
上一篇:Salesforce LWC学习(三十六) Quick Action 支持选择 LWC了


下一篇:Mybatis系列全解(八):Mybatis的9大动态SQL标签你知道几个?提前致女神!