使用Java doc注释你的代码，生成规范的文档

简介

Javadoc用于描述类或者方法的作用。Javadoc可以写在类上面和方法上面。

用于注释类

写在类上注释可以分为三段：

• 第一段:概要描述，一句话说明类的作用，以

  开头以“.”结尾。

@link：{@link 包名.类名#方法名(参数类型)}用于快速链接到相关代码。

示例

/**
 * Miscellaneous {@link String} utility methods.
 * 
 */
public abstract class StringUtils {
}

@code： {@code text} 将文本标记为code。

// 完全限定的类名
{@link java.lang.Character}

// 省略包名
{@link String}

// 省略类名，表示指向当前的某个方法
{@link #length()}

// 包名.类名.方法名(参数类型)
{@link java.lang.String#charAt(int)}

• 第二段:详细描述，详细描述类的作用，可以写多段，都是以

  开头，以“.”结尾。其中可以添加对类的使用方法的示例，示例使用

  包括起来。

@param：一般类中支持泛型时会通过@param来解释泛型的类型。

/**
* @param  the type of elements in this list
*/
public interface List extends Collection {}

• 第三段，文档标注，用于@author标注作者，@since标注文档的起始版本号，@version当前版本号，等等。

完整示例:

image

代码：

/**
 * 类{@code CoidsDataSource}初始化codis连接池
 *
 * 
创建一个codis连接池
 * 
 * 使用方法
 * @Autowired
 * private JedisResourcePool jedisResourcePool;
 * 获取一个jedis连接
 * Jedis jedis = jedisResourcePool.getResource();
 * 回收jedis连接
 * jedis.close();
 *
 * 
 *
 * @author Alex Han
 * @since 1.0
 * @version 1.2
 *
 */

public class CoidsDataSource {}

用于注释方法

• 第一段：概要描述，通常用一句或者一段话简要描述该方法的作用，以“.”结尾。
• 第二段：详细描述，通常用多段话详细描述方法的作用、使用方法等，以“.”结尾。
• 第三段：文档标注，@param标注参数，@return标注返回值，@exception标注解异常，@see标注另请参阅。

完整示例：

image

代码:

    /**
     * 根据传入的Array初始化一个名为setName的redis资产
     * 
HttpMethod:Post
     * 
URL:/msg-producer/test/init/selfDevice
     *
     * @param setName redis set 名称
     * @param array 资产json array
     * @return {@code ResultData}
     */
    @ApiOperation(value ="初始化自己的资产",httpMethod = "POST")
    @PostMapping("/init/selfDevice")
    public ResultData initJedisSelfDevice(String setName,String array){
        JSONArray jsonArray = JSONArray.parseArray(array);
        Jedis jedis = jedisResourcePool.getResource();
        for(int i = 0 ; i < jsonArray.size() ; i ++){
            jedis.sadd(setName,jsonArray.get(i).toString());
        }
        jedis.close();
        return new ResultData<>(null, ResultStatus.initStatus(StatusEnum.SUCCESS));
    }

使用IDEA生成Java doc

点击菜单Tools->Generate Javadoc,进行以下操作：

image

点击ok，生成的文档页面会在浏览器自动打开，同时在配置的目录也生成了文档。

生成的文档：

image

image

选择一个类,格式如下:

image

方法格式如下:

image

使用maven-javadoc-plugin生成javadoc.jar

在maven pom中配置：

    org.apache.maven.plugins
    maven-javadoc-plugin
    2.10.2
    
        true
    
    
        
            attach-javadocs
            
                jar
            
        
    

使用mvn package命令打包。生成的javadoc.jar。

image