簡(jiǎn)介

Javadoc用于描述類或者方法的作用。Javadoc可以寫(xiě)在類上面和方法上面。

用于注釋類

寫(xiě)在類上注釋可以分為三段：

• 第一段:概要描述，一句話說(shuō)明類的作用，以<p>開(kāi)頭以“.”結(jié)尾。

@link：{@link 包名.類名#方法名(參數(shù)類型)}用于快速鏈接到相關(guān)代碼。

示例

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

@code： {@code text} 將文本標(biāo)記為code。

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

// 省略包名
{@link String}

// 省略類名，表示指向當(dāng)前的某個(gè)方法
{@link #length()}

// 包名.類名.方法名(參數(shù)類型)
{@link java.lang.String#charAt(int)}

• 第二段:詳細(xì)描述，詳細(xì)描述類的作用，可以寫(xiě)多段，都是以<p>開(kāi)頭，以“.”結(jié)尾。其中可以添加對(duì)類的使用方法的示例，示例使用<pre></pre>包括起來(lái)。

@param：一般類中支持泛型時(shí)會(huì)通過(guò)@param來(lái)解釋泛型的類型。

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

• 第三段，文檔標(biāo)注，用于@author標(biāo)注作者，@since標(biāo)注文檔的起始版本號(hào)，@version當(dāng)前版本號(hào)，等等。

完整示例:

image

代碼：

/**
 * 類{@code CoidsDataSource}初始化codis連接池
 *
 * <p>創(chuàng)建一個(gè)codis連接池</p>
 * <pre class="code">
 * 使用方法
 * &#64;Autowired
 * private JedisResourcePool jedisResourcePool;
 * 獲取一個(gè)jedis連接
 * Jedis jedis = jedisResourcePool.getResource();
 * 回收jedis連接
 * jedis.close();
 *
 * </pre>
 *
 * @author Alex Han
 * @since 1.0
 * @version 1.2
 *
 */

public class CoidsDataSource {}

用于注釋方法

• 第一段：概要描述，通常用一句或者一段話簡(jiǎn)要描述該方法的作用，以“.”結(jié)尾。
• 第二段：詳細(xì)描述，通常用多段話詳細(xì)描述方法的作用、使用方法等，以“.”結(jié)尾。
• 第三段：文檔標(biāo)注，@param標(biāo)注參數(shù)，@return標(biāo)注返回值，@exception標(biāo)注解異常，@see標(biāo)注另請(qǐng)參閱。

完整示例：

image

代碼:

    /**
     * 根據(jù)傳入的Array初始化一個(gè)名為setName的redis資產(chǎn)
     * <p>HttpMethod:Post</p>
     * <p>URL:/msg-producer/test/init/selfDevice</p>
     *
     * @param setName redis set 名稱
     * @param array 資產(chǎn)json array
     * @return {@code ResultData}
     */
    @ApiOperation(value ="初始化自己的資產(chǎn)",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

點(diǎn)擊菜單Tools->Generate Javadoc,進(jìn)行以下操作：

image

點(diǎn)擊ok，生成的文檔頁(yè)面會(huì)在瀏覽器自動(dòng)打開(kāi)，同時(shí)在配置的目錄也生成了文檔。

生成的文檔：

image

image

選擇一個(gè)類,格式如下:

image

方法格式如下:

image

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

在maven pom中配置：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.2</version>
    <configuration>
        <aggregate>true</aggregate>
    </configuration>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

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

image