簡介

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

用于注釋類

寫在類上注釋可以分為三段：

• 第一段:概要描述，一句話說明類的作用，以<p>開頭以“.”結尾。

@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)}

• 第二段:詳細描述，詳細描述類的作用，可以寫多段，都是以<p>開頭，以“.”結尾。其中可以添加對類的使用方法的示例，示例使用<pre></pre>包括起來。

@param：一般類中支持泛型時會通過@param來解釋泛型的類型。

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

• 第三段，文檔標注，用于@author標注作者，@since標注文檔的起始版本號，@version當前版本號，等等。

完整示例:

image

代碼：

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

public class CoidsDataSource {}

用于注釋方法

• 第一段：概要描述，通常用一句或者一段話簡要描述該方法的作用，以“.”結尾。
• 第二段：詳細描述，通常用多段話詳細描述方法的作用、使用方法等，以“.”結尾。
• 第三段：文檔標注，@param標注參數，@return標注返回值，@exception標注解異常，@see標注另請參閱。

完整示例：

image

代碼:

    /**
     * 根據傳入的Array初始化一個名為setName的redis資產
     * <p>HttpMethod:Post</p>
     * <p>URL:/msg-producer/test/init/selfDevice</p>
     *
     * @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中配置：

<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