简介

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>创建一个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