Javadoc了解

引用百度百科的说法：javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。

 

使用方法：使用命令行在目标文件所在目录输入javadoc +文件名.java。

 

//参考博客：https://blog.csdn.net/vbirdbest/article/details/80296136

 

Javadoc注释规范：

//  注释单行

/ *           */ 注释若干行

/**   ……*/ 注释若干行，写入Javadoc文档

 

Ⅰ.写在类上的Javadoc

① 第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束

示例1（单行）：

package org.springframework.util;

/**
 * Miscellaneous {@link String} utility methods.
 *
 */

public abstract class StringUtils {

 

 

示例2（多行）：

/**
 * 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.
 */

② 第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束

示例：

package org.springframework.util;

/**
 * Miscellaneous {@link String} utility methods.
 *
 * <p>Mainly for internal use within the framework; consider
 * <a href="http://commons.apache.org/proper/commons-lang/">Apache's Commons Lang</a>
 * for a more comprehensive suite of {@code String} utilities.
 *
 * <p>This class delivers some simple functionality that should really be
 * provided by the core Java {@link String} and {@link StringBuilder}
 * classes. It also provides easy-to-use methods to convert between
 * delimited strings, such as CSV strings, and collections and arrays.
 *
 */

 

③ 第三段：文档标注，用于标注作者、创建时间、参阅类等信息

 

注：详细描述一般用一段或者几个锻炼来详细描述类的作用，详细描述中可以使用html标签，如<p>、<pre>、<a>、<ul>、<i>等标签。

通常详细描述都以段落p标签开始。

详细描述和概要描述中间通常有一个空行来分割

 

Ⅱ：Javadoc标签

标签	说明
@author 作者	作者标识
@version 版本号	版本号
@param 参数名 描述	方法的入参名及描述信息，如入参有特别要求，可在此注释。
@return 描述	对函数返回值的注释
@deprecated 过期文本	标识随着程序版本的提升，当前API已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个API。
@throws异常类名	构造函数或方法所会抛出的异常。
@exception 异常类名	同@throws。
@see 引用	查看相关内容，如类、方法、变量等。
@since 描述文本	API在什么程序的什么版本后开发支持。
{@link包.类#成员 标签}	链接到某个特定的成员对应的文档中。
{@value}	当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。