引用百度百科的说法: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="https://my.oschina.net//u/4411838/blog/4175340/span>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}
当对常量进行注释时,如果想将其值包含在文档中,则通过该标签来引用常量的值。