简介
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">
* 使用方法
* @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
