zoukankan      html  css  js  c++  java

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

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

     

    目录(?)[+]

     

    需求

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

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

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

    基本使用

            插件的基本配置很简单：

    [html] view plaincopy在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 plaincopy在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 plaincopy在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 plaincopy在CODE上查看代码片派生到我的代码片
     
    1. /**  
    2.  * 根据Id获得页面所含操作  
    3.  * @param ID 页面所含操作ID  
    4.  */  
    5.  PageOperation getOperationByID(String ID);  

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

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

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

    [html] view plaincopy在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，如果写了，那么显示效果如下：

                    

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

    自定义路径

            这个功能一般不会用到，只是顺便看了一下，就写下来吧。
            在这里需要叨念两句关于约定优于配置，在最初我用Maven的时候，就看到过这样的话，Maven目录可以不这样设置么？可以，你可以自己改。
            只能说我们在大部分时候，是不需要改这个，但不意味着我们在做的时候就可以把这个做死，这样于用户，于今后的维护来说，都不是一个好的选择。
            两句叨念完了，现在来看怎么设置吧：
    [html] view plaincopy在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文档过程中遇到的问题就都解决了。
  • 相关阅读:
    坑爹的PostgreSQL的美元符号（有时需要替换成单引号）
    DataFrame的apply用法
    Pytorch写CNN
    Pytorch分类和准确性评估--基于FashionMNIST数据集
    设置Mac终端、pip、Anaconda、PyCharm共用一套环境
    Python编程基本规范
    【转】动态规划：最长递增子序列Longest Increasing Subsequence
    动态规划--找零钱
    在线编写复杂的数学公式--EdrawMath
    pandas如何逐行需改DataFrame
  • 原文地址：https://www.cnblogs.com/adolfmc/p/5066562.html
Copyright © 2011-2022 走看看