Java注释

最新推荐文章于 2025-06-30 19:02:33 发布

JWbonze

最新推荐文章于 2025-06-30 19:02:33 发布

阅读量687

点赞数

CC 4.0 BY-SA版权

分类专栏： # Java SE 文章标签：文档注释 Java注释 javadoc 生成API

本文链接：https://blog.youkuaiyun.com/JWbonze/article/details/85010169

Java SE 专栏收录该内容

23 篇文章

订阅专栏

2.5.使用javadoc命令生成API文档

2.5.1.说明

2.5.2.操作截图

注释，英文comment，程序中需要添加注释用来说明某段代码的作用，增强代码的可读性。注释并不会被JVM解释执行，所以可以在Java源程序中根据需要添加任意多的注释。也正是因为这点，我们可以给程序的某段代码加上注释来对程序进行简单的调试、验证。

1.注释分类

在Java中有3种类型的注释，分别是单行注释、多行注释和文档注释。

1.1.单行注释

单行注释的作用是注释一行代码。它是使用双斜线（//）标注的，注释的内容放在“//”的后面。
【语法】
//单行注释内容

1.2.多行注释

如果我们想同时注释连续的多行代码，可以使用多个单行注释。但是这种方式太过繁琐，我们可以直接使用多行注释的方式。
多行注释的作用是注释连续的多行内容。它把注释的内容放在“/*”开始，“*/”结束的区域内。
【语法】
/*
这是多行注释1
这是多行注释2
*/
【注意】
（1）多行注释内容可以含有单行注释，但是多行注释内部不能再嵌套多行注释。
（2）大部分时候多行注释的每一行行首都有一个“*”，这是编辑器自动添加的。除了必须的开始、结束标记外，其余“*”都是可以去掉。

1.3.文档注释

单行注释和多行注释是大多数程序语言共有的，Java语言在二者之上还有自己独有的文档注释。
文档注释的好处是将分离的代码和注释连接起来，保证代码与注释内容可以同时更新。除此之外，文档注释还可以生成API文档。
文档注释以“/**”开始，“*/”结束，中间的内容全部都是文档注释。
【语法】
/**
文档注释
*/
不过，要想保证代码与注释同时更新，仅使用“/** ”、“*/”这两个符号是不够的，还要使用到文档注释的标签，也可以称为“标记”。
文档注释的标记是什么、完整的文档注释应该怎么编写、如何将文档注释生成API见“2.文档注释生成API文档”。下面是3种注释的示例。

package study._07Comments;
/**
 * 主题：Java中的注释
 *
 *
 *	
 * @author LingZhang
 * 
 */

public class Demo01_Comments {
	/**
	 * 【文档注释】
	 * @param 字符串数组
	 * @return void类型
	 */
	public static void main(String[] args) {
		/*
		 * 【多行注释】
		 * System类字段out
		 */
		System.out.println("Hello World!");//【单行注释】输出内容为Hello World!
	}
}

2.文档注释生成API文档

前面说了单行注释与多行注释，对文档注释一笔带过，现在具体说一下文档注释。文档注释的作用主要有两点：保证了代码与注释的同步更新；可以使用javadoc工具将文档注释生成API文档。

2.1.文档注释语法

一个文档注释由两部分组成：描述部分和标记部分。下面就是文档注释的语法。
【语法】
/**
描述部分：可以使用HTML标签。

标记部分：使用规定的javadoc标记。
*/
描述部分是一些概要性文本，描述了所注释的代码的大概信息。javadoc会将这些句子抽取出来形成单独一页。文档注释生成的API文档是以HTML文件形式存在的，所以在描述部分这种说明性文字中可以使用HTML标签，比如段落标签，加粗。不过并不是所有HTML标签都可以使用的，这点值得注意，比如、 等，下面两图就是这两种标签的报错情况。

文档注释核心部分就是“标记部分”，这些标记由“@”符号和标签词汇组成，后面接具体的解释说明信息。

2.2.常用的文档注释标记

文档注释标记的语法通常是@开头，后面紧接标记词汇。也有二者被{}包裹的语法。
下面是常用的文档注释标记：
（1）@author：指定Java程序的作者。
（2）@deprecated：过时的方法，即该方法不推荐使用。注意：从JDK5 开始，该标记已经被注解@Deprecated所代替。[deprecated: 不赞成；弃用；不宜用]
（3）@exception：抛出异常的类型。
（4）@param：方法的参数说明信息。
（5）@return：方法的返回值说明信息。
（6）@see：指定当前页面到另一个页面的链接。也可以指定另一个类及其内部，语法是“类、类#方法、类#成员”。
（7）@since：表示该变量或方法在哪个版本被引入。
（8）@throws：对异常进行说明。@throws以前使用的是@exception。
需要说明的是（花费了半个多小时得到的结论），该说明文字应该另起一行，否则会报错。

	/**
	 * add方法作用是求两个整数之商。
	 * 
	 * @param a，int类型，作为被除数
	 * @param b，int类型，作为除数
	 * @return c，int类型，是a除以b的商
	 * @throws java.lang.ArithmeticException   如果除数是0，该方法会报ArithmeticException异常
	 * @see java.math.BigDecimal#divide
	 */
	public static int div(int a,int b){
		int c=a/b;
		return c;
	}

报错：

（9）@version：指定Java程序的版本。
（10）{@link} ：插入一个到另一个主题的链接。
（11）{@value}：用于生成被标记的常量字段的值。

2.3.文档注释位置

文档注释不像单行注释、多行注释那样可以注释在代码的任意位置。由于文档注释是对Java程序包、类和接口、构造方法、public或protected修饰的成员变量和方法进行解释说明，所以文档注释就要位于这些代码的上方。
根据文档注释的位置不同，我们大致可以将文档注释分为三类：类或接口注释、方法（包括构造方法和普通方法）注释、成员变量（Field）注释。
可以出现在类或者接口文档注释的有:@see、@depracated、@author、@version等；
可以出现在public或protected修饰的方法或构造方法文档注释中的有@see、@deprecated、@param、@return、@throw、@exception等；
可以出现在public或protected修饰的成员变量的文档注释中的有@see、@deprecated等。
值得注意的是，每个标记独占一行，多个相同的标记上下相邻。

2.4.文档注释案例

方法上面的文档注释规范写法是解释内容另起一行，这样就不会报错了，格式如下：

@标记参数

解释说明文字

package study._07Comments;
/**
 * 
 * 这个类是用来描述<b>文档注释</b>的一个例子，类名是Demo02_DocumentationComment。
 * 文档注释大致可以标记在三个位置：
 * <ol>
 * 		<li>类和接口</li>
 * 		<li>成员变量</li>
 * 		<li>构造方法和普通方法</li>
 * </ol>
 * 现在就让我们开始学习文档注释吧！
 * 	
 * @author LingZhang
 * @version 3.0
 * @see <a href="https://www.oracle.com/index.html">Oracle</a>
 * @see <a href="https://www.java.com/zh_CN/">Java</a>
 */
public class Demo02_DocumentationComments {
	/**
	 * num是一个静态成员变量
	 * @since 2.0
	 */
	public static int num;
	
	/**
	 * text是一个实例成员变量
	 */
	protected String text;
	
	/**
	 * add方法作用是求两个整数之商。
	 * 
	 * @param a
	 * 			int类型，作为被除数
	 * @param b
	 * 			int类型，作为除数
	 * @return c
	 * 			int类型，是a除以b的商
	 * @throws java.lang.ArithmeticException  
	 * 		    如果除数是0，该方法会报ArithmeticException异常
	 * @see java.math.BigDecimal#divide
	 */
	public static int div(int a,int b){
		int c=a/b;
		return c;
	}
		
}

2.5.使用javadoc命令生成API文档

文档注释的一个重要功能是通过javadoc工具直接将源代码里的文档注释生成为一份API文档，API文档中不会包含源代码中的单行注释和多行注释。
我们在安装JDK的时候就已经安装了javadoc工具，所以可以在命令行中直接使用。
javadoc工具的语法如下：
【语法】
javadoc [-d 存储路径 -windowtitle 文本] 源文件.java

2.5.1.说明

（1）上述语法格式中，javadoc支持通配符，比如*.java就表示当前路径下所有java文件。
（2）“[]”里面的内容是可选命令参数，javadoc常用可选命令参数有如下几个：
-d：英文directory，该参数指定一个路径，用于将生成的API文档放到指定目录下。如果没有该参数，那么生成的文档直接在java源文件目录中。
-windowtitle：该选项指定一个字符串，用于设置API文档的浏览器窗口标题。
-public：仅显示 public 类和成员。
-protected：显示 protected/public 类和成员 (缺省)。
除此之外，javadoc命令还包含了大量其他参数，我们可以通过在命令行窗口执行javadoc -help命令来查看javadoc命令的所有参数。