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

时间：2021-12-21 09:35:27

需求

        近期要对一个项目结构例如以下的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文档过程中遇到的问题就都攻克了。
标签：

相关文章