1. 类上的 JavaDoc 注释结构
基本结构
- 第一段：概要描述（一句或一段话，以英文句号结束）
- 第二段：详细描述（一段或多段话，每段以英文句号结束）
- 第三段：文档标注（作者、创建时间、参阅类等信息）
单行示例
/**
* Utility class used to help generate return values for calls to {@link Object#toString()}.
*/
public class ToStringUtil {
多行示例
/**
* Class {@code Object} is the root of the class hierarchy.
* Every class has {@code Object} as a superclass. All objects,
* including arrays, implement the methods of this class.
*
* @author unascribed
* @see java.lang.Class
* @since JDK1.0
*/
public class Object {
2. 常用 JavaDoc 标签详解
链接相关标签
@link - 创建代码链接
package cn.peiluming.test;
/**
* {@link cn.peiluming.test.JavaDoc#main(String[])} // 完全限定
* {@link JavaDoc#main(String[])} // 省略包名
* {@link #main(String[])} // 省略类名（当前类）
* {@link cn.peiluming.test.JavaDoc} // 完全限定类名
*
* @author 裴路明
* @create 2021/1/15 22:16
*/
public class JavaDoc {
public static void main(String[] args) {}
}
@code - 标记代码文本
- 将文本标记为
<code>text</code> - 最佳实践：涉及类名或方法名时都应使用
@code
详细描述格式
- 可使用 HTML 标签：
<p>、<pre>、<a>、<ul>、<i>等 - 通常以
<p>标签开始 - 详细描述与概要描述间用空行分割
package org.thymeleaf.util;
/**
* Utility methods for String objects.
*
* <p>
* This class is used as a basis for the methods offered by
* {@link org.thymeleaf.expression.Strings}, which in turn are the
* methods offered by the {@code #strings} utility object in variable
* expressions.
* </p>
*
* @author Daniel Fernández
* @author Le Roux Bernard
* @author Soraya Sánchez Labandeira
* @since 1.0
*/
public final class StringUtils {
泛型参数说明
/**
* @param <E> the type of elements in this list
*/
public interface List<E> extends Collection<E> {}
作者信息 @author
支持多种格式：
// 纯文本作者
@author Rod Johnson
// 纯文本作者 + 邮件
@author Igor Hersht, igorh@ca.ibm.com
// 超链接邮件
@author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
// 纯文本邮件
@author shane_curcuru@us.ibm.com
// 纯文本组织
@author Apache Software Foundation
// 超链接组织
@author <a href="https://jakarta.apache.org/turbine">Apache Jakarta Turbine</a>
相关引用 @see
/**
* @see IntStream
* @see LongStream
* @see DoubleStream
* @see <a href="package-summary.html">java.util.stream</a>
*/
public interface Stream<T> extends BaseStream<T, Stream<T>> {}
版本信息
// @since - 标记创建版本或时间
@since 1.8
@since 16 April 2001
// @version - 标记当前版本
@version 1.0
3. 方法上的 JavaDoc 注释结构
基本结构
- 第一段：概要描述（方法作用，英文句号结束）
- 第二段：详细描述（详细说明，英文句号结束）
- 第三段：文档标注（参数、返回值、异常等）
参数和返回值
/**
* 根据博客Id和标签Id插入中间表
*
* @param blogId 博客Id
* @param tagId 标签Id
* @return 影响行数
*/
int insertBlogsTags(@Param("blogId") String blogId, @Param("tagId") String tagId);
异常处理
/**
* 文件复制
*
* @param src 源目录
* @param destDir 目标目录
* @param fileName 文件名
* @throws IOException IO异常
*/
private void copyFile(String src, String destDir, String fileName) throws IOException {
/**
* @exception SQLException if a database error occurs
*/
protected Connection open() throws SQLException {
其他常用标签
@see - 参考方法
/**
* @see java.net.URLDecoder#decode(String, String)
*/
public static String uriDecode(String source, Charset charset){}
@value - 常量值
/** 默认数量 {@value} */
private static final Integer QUANTITY = 1;
@inheritDoc - 继承文档
/**
* Returns the URI of this engine.
* @return the URI
*/
public abstract String engineGetURI();
/** @inheritDoc */
public final String engineGetURI() {
return Canonicalizer.ALGO_ID_C14N_OMIT_COMMENTS;
}
@docRoot - 文档根路径
/**
* Is this Doc item an
* <a href="{@docRoot}/com/sun/javadoc/package-summary.html#class">ordinary
* class</a>?
* (i.e. not an interface, annotation type, enum, exception, or error)?
*
* @return true if it represents an ordinary class
*/
boolean isOrdinaryClass();
@deprecated - 废弃标记
/**
* @deprecated
*/
@Deprecated
public void invoke(java.rmi.server.RemoteCall call) throws Exception {
4. JavaDoc 生成配置
IDEA 生成步骤
- 菜单：Tools → Generate JavaDoc
推荐配置参数
-encoding UTF-8 -charset UTF-8 -windowtitle "XXwiki" -link http://docs.oracle.com/javase/7/docs/api
参数说明
-encoding UTF-8：源代码编码格式-charset UTF-8：生成文档的字符集-windowtitle：浏览器窗口标题-link：外部类引用超链接
-link 参数作用
- 不指定
-link：显示全限定名java.lang.String - 指定
-link：显示短名称String并自动创建超链接到官方文档 - 原理：通过
package-list文件映射外部类的全限定名
生成建议
- 源代码范围：不建议整个 Project
- 输出目录：指定专门的文档目录
- 语言版本：建议填写
zh_CN生成中文文档
