您的位置：首页 > 编程语言 > Java开发

多模块Maven项目如何使用javadoc插件生成文档

2015-12-22 14:34 971 查看

版权声明：本文为博主原创文章，未经博主允许不得转载。

目录(?)[+]

需求

基本使用

插件的基本配置很简单：

[html] view plain copy

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-javadoc-plugin</artifactId>

<version>2.9.1</version>

</plugin>

如果对于一个普通的Maven项目，那么这个配置就可以让你输出一个JavaDoc文档了（使用javadoc:javadoc命令）。

多模块Maven项目

而我们现在是一个多模块的Maven项目，那么就需要一些额外的配置来完成此操作：

[html] view plain copy

<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。

自定义标签

现在问题来了：

我们的类中的方法注释如下

[html] view plain copy

/**

* @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那样让方法的描述紧跟在方法名后面，是需要这样添加注释的：

[html] view plain copy

/**

* 根据Id获得页面所含操作

* @param ID 页面所含操作ID

*/

PageOperation getOperationByID(String ID);

已经到了项目后期，现在再让大家去改这些有些说不过去，查了下官网，发现有自定义标签，正好解决的就是这样的问题。

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

废话不多说，直接看例子：

[html] view plain copy

<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，如果写了，那么显示效果如下：

这样，你就既可以定义自己的注释规范，又可以生成相应的JavaDoc文档了

自定义路径

这个功能一般不会用到，只是顺便看了一下，就写下来吧。
在这里需要叨念两句关于约定优于配置，在最初我用Maven的时候，就看到过这样的话，Maven目录可以不这样设置么？可以，你可以自己改。
只能说我们在大部分时候，是不需要改这个，但不意味着我们在做的时候就可以把这个做死，这样于用户，于今后的维护来说，都不是一个好的选择。
两句叨念完了，现在来看怎么设置吧：

[html] view plain copy

<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文档过程中遇到的问题就都解决了。

内容来自用户分享和网络整理，不保证内容的准确性，如有侵权内容，可联系管理员处理

标签：

相关文章推荐

新的分享

章节导航