需求
最近要對一個項目結構如下的Maven項目生成JavaDoc文檔。
Project
|-- pom.xml
|-- Module1
| `-- pom.xml
|-- Module2
| `-- pom.xml
|-- Module3
|-- pom.xml
這個就需要用到本文將要提出的一個Maven插件：javadoc。
基本使用
插件的基本配置很簡單：
[html]
view plaincopy<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
</plugin>
如果對于一個普通的Maven項目，那么這個配置就可以讓你輸出一個JavaDoc文檔了（使用javadoc:javadoc命令）。
多模塊Maven項目
而我們現(xiàn)在是一個多模塊的Maven項目，那么就需要一些額外的配置來完成此操作：
[html]
view plaincopy<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。
自定義標簽
現(xiàn)在問題來了：
我們的類中的方法注釋如下
[html]
view plaincopy/**
* @author : 張三
* @group : group
* @Date : 2014-01-26 21:14:49
* @Comments : 頁面所含操作增刪改查的ejb接口
* @Version : 1.0.0
*/
public interface IOperationBean {
/**
* @MethodName : getOperationByID
* @Description : 根據(jù)Id獲得頁面所含操作
* @param ID 頁面所含操作ID
*/
PageOperation getOperationByID(String ID);
}
而我們在生成JavaDoc后，并沒有看到Description和MethodName這兩個注解中對應的內(nèi)容。也就導致了方法的說明不翼而飛了。 經(jīng)過實驗，要想像jdk那樣讓方法的描述緊跟在方法名后面，是需要這樣添加注釋的：
[html]
view plaincopy/**
* 根據(jù)Id獲得頁面所含操作
* @param ID 頁面所含操作ID
*/
PageOperation getOperationByID(String ID);
已經(jīng)到了項目后期，現(xiàn)在再讓大家去改這些有些說不過去，查了下官網(wǎng)，發(fā)現(xiàn)有自定義標簽，正好解決的就是這樣的問題。
而這次問題的出現(xiàn)，還是源于我們對于JavaDoc生成不熟悉。
廢話不多說，直接看例子：
[html]
view plaincopy<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這個在
官網(wǎng)上有8種，我也自己試了下，其實這個就是說你要把哪些（方法、字段、類）上面的注解放到JavaDoc中
3.head，如果不寫這個，用的就是name，如果寫了，那么顯示效果如下：
這樣，你就既可以定義自己的注釋規(guī)范，又可以生成相應的JavaDoc文檔了
自定義路徑
這個功能一般不會用到，只是順便看了一下，就寫下來吧。
在這里需要叨念兩句關于約定優(yōu)于配置，在最初我用Maven的時候，就看到過這樣的話，Maven目錄可以不這樣設置么？可以，你可以自己改。
只能說我們在大部分時候，是不需要改這個，但不意味著我們在做的時候就可以把這個做死，這樣于用戶，于今后的維護來說，都不是一個好的選擇。
兩句叨念完了，現(xiàn)在來看怎么設置吧：
[html]
view plaincopy<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文檔過程中遇到的問題就都解決了。
