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

 

目录(?)[+]

 

需求

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

                Project
                        |-- pom.xml
                        |-- Module1
                                |   `-- pom.xml
                        |-- Module2
                                |   `-- pom.xml
                        |-- Module3
                                |-- pom.xml

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

 

基本使用

        插件的基本配置很简单:

 

[html]  view plain copy 在CODE上查看代码片
 
  1. <plugin>  
  2.     <groupId>org.apache.maven.plugins</groupId>  
  3.     <artifactId>maven-javadoc-plugin</artifactId>  
  4.     <version>2.9.1</version>  
  5. </plugin>  

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

 

 

多模块Maven项目

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

 

[html]  view plain copy 在CODE上查看代码片
 
  1. <plugin>  
  2.     <groupId>org.apache.maven.plugins</groupId>  
  3.     <artifactId>maven-javadoc-plugin</artifactId>  
  4.     <version>2.9.1</version>  
  5.     <configuration>  
  6.         <aggregate>true</aggregate>  
  7.     </configuration>  
  8. </plugin>  

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

 

 

自定义标签

        现在问题来了:

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

 

[html]  view plain copy 在CODE上查看代码片
 
  1. /**  
  2.  * @author     : 张三  
  3.  * @group      : group  
  4.  * @Date       : 2014-01-26 21:14:49  
  5.  * @Comments   : 页面所含操作增删改查的ejb接口  
  6.  * @Version    : 1.0.0  
  7.  */  
  8. public interface IOperationBean {  
  9.         /**  
  10.          * @MethodName  : getOperationByID  
  11.          * @Description : 根据Id获得页面所含操作  
  12.          * @param ID 页面所含操作ID  
  13.          */  
  14.          PageOperation getOperationByID(String ID);  
  15. }  

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

 

        经过实验,要想像jdk那样让方法的描述紧跟在方法名后面,是需要这样添加注释的:

 

[html]  view plain copy 在CODE上查看代码片
 
  1. /**  
  2.  * 根据Id获得页面所含操作  
  3.  * @param ID 页面所含操作ID  
  4.  */  
  5.  PageOperation getOperationByID(String ID);  

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

 

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

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

 

[html]  view plain copy 在CODE上查看代码片
 
  1. <plugin>  
  2.     <groupId>org.apache.maven.plugins</groupId>  
  3.     <artifactId>maven-javadoc-plugin</artifactId>  
  4.     <version>2.9.1</version>  
  5.     <configuration>  
  6.         <aggregate>true</aggregate>  
  7.         <tags>  
  8.             <tag>  
  9.                 <name>Description</name>  
  10.                 <placement>a</placement>  
  11.                 <head>用途</head>  
  12.             </tag>  
  13.         </tags>  
  14.     </configuration>  
  15. </plugin>  

        说明:

 

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

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

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

                多模块Maven项目如何使用javadoc插件生成文档_第1张图片

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

自定义路径

        这个功能一般不会用到,只是顺便看了一下,就写下来吧。
        在这里需要叨念两句关于约定优于配置,在最初我用Maven的时候,就看到过这样的话,Maven目录可以不这样设置么?可以,你可以自己改。
        只能说我们在大部分时候,是不需要改这个,但不意味着我们在做的时候就可以把这个做死,这样于用户,于今后的维护来说,都不是一个好的选择。
        两句叨念完了,现在来看怎么设置吧:
[html]  view plain copy 在CODE上查看代码片
 
  1. <plugin>  
  2.     <groupId>org.apache.maven.plugins</groupId>  
  3.     <artifactId>maven-javadoc-plugin</artifactId>  
  4.     <version>2.9.1</version>  
  5.     <configuration>  
  6.         <reportOutputDirectory>../myoutput</reportOutputDirectory>  
  7.         <destDir>myapidocs</destDir>  
  8.     </configuration>  
  9. </plugin>  

        说明:
        1.reportOutputDirectory是说的路径
        2.destDir是说的目标文件夹
        
        到这里Maven多模块下使用javadoc插件生成JavaDoc文档过程中遇到的问题就都解决了。

你可能感兴趣的:(多模块Maven项目如何使用javadoc插件生成文档)