Java注释

小灰灰 2022-04-04 04:47 213阅读 0赞

**目录**

1.注释分类

1.1.单行注释

1.2.多行注释

1.3.文档注释

2.文档注释生成API文档

2.1.文档注释语法

2.2.常用的文档注释标记

2.3.文档注释位置

2.4.文档注释案例

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标签都可以使用的，这点值得注意，比如、 等，下面两图就是这两种标签的报错情况。 
 ![20181214220719776.png][] 
 ![20181214220741869.png][] 
    文档注释核心部分就是“标记部分”，这些标记由“@”符号和标签词汇组成，后面接具体的解释说明信息。

##    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;
    	}

报错：

![20181214220946649.png][]  
   
（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;
 /**
 * 
 * 这个类是用来描述文档注释的一个例子，类名是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命令的所有参数。

### 2.5.2.操作截图 ###

下面是使用javadoc命令对案例2.4进行操作的截图：  
（1）命令行输入命令  
 ![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0pXYm9uemU_size_16_color_FFFFFF_t_70][]  
（2）本地生成的API文档  
 ![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0pXYm9uemU_size_16_color_FFFFFF_t_70 1][]  
（3）打开API文档

下面就是生成的API文档正文：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0pXYm9uemU_size_16_color_FFFFFF_t_70 2][]

下面是对API中生成的内容和文档注释的对比：  
 ![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0pXYm9uemU_size_16_color_FFFFFF_t_70 3][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0pXYm9uemU_size_16_color_FFFFFF_t_70 4][]

Over，2018年12月24日第一版

[20181214220719776.png]: /images/20220404/647a19e102504f659372112d940b4c6c.png
[20181214220741869.png]: /images/20220404/bea80789168a4bc39deb61bfa323df88.png
[20181214220946649.png]: /images/20220404/fdaffe6103b240aabd885189a78578a3.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0pXYm9uemU_size_16_color_FFFFFF_t_70]: /images/20220404/8d86d260e4354153b6b33b27b3de2344.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0pXYm9uemU_size_16_color_FFFFFF_t_70 1]: /images/20220404/f9d3272a0b1349b7ae9f337f11db601f.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0pXYm9uemU_size_16_color_FFFFFF_t_70 2]: /images/20220404/a64f8cb99ecc4430a3c765ef1b9d3cf3.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0pXYm9uemU_size_16_color_FFFFFF_t_70 3]: /images/20220404/02d65ee3e233479d84d35afe9d4b4a1a.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0pXYm9uemU_size_16_color_FFFFFF_t_70 4]: /images/20220404/65a6e30dbdb3452ca07aa328c370a8ba.png