NO.13 --- Java 注释

作者: 捌千里路雲和月 | 来源:发表于2023-02-21 12:36 被阅读0次

Java学习笔记
javaSE回顾_02
Java中的注释、关键字、标识符
Kotlin语言基础（二）
Java基础复习
3.注释（Comment）
scala(二) 变量与数据类型
IDEA-注释模版设置
kotlin精讲-第2章（4）注释和异常
IDEA使用小技巧

笔记内容：
一、注释。
二、代码实践。

一、注释。

1.1、注释是对代码的解释和说明。目的是为了让别人和自己很容易看懂这段代码有什么用途。
1.2、注释应简洁明了的表达该有的意思。
1.3、注释的三种形式：
1.3.1、单行注释，表示方式用 // 内容。有效范围至行尾。作用域全文皆可用。
1.3.2、多行注释，表示方式用 /* 内容 */ ，可用作单行或多行注释。有效范围 / * */ 之间。作用域全文皆可用。
1.3.3、doc 文档注释，表示方式用 /** 内容 */ ，可用作单行或多行注释。有效范围 / ** */ 之间，doc 文档注释作用域的特殊性，它在类前面和方法前面才能生成 doc 文档。其余范围只是普通的文中注释。
1.4、注释不影响程序运行。

二、代码实践。

2.1、com.elementaryJava 目录下创建 lesson03 包，包下创建 annotation 类。

2.2、在 annotation 类中进行了多样注释。
2.2.1、第 2、4 点以 // 开头的是单行注释，有效范围只在于单行。
2.2.2、第 1 点以 /** 开头，中间包裹内容，* / 结尾的形式属于多行注释。它的有效范围是 /** * / 内任意行。这种以 / * * 开头，* / 结尾的注释形式在类的开头和方法的开头可以在 doc 文档中显示注释内容。
2.2.3、第 3 点以 /* */ 包裹的内容是多行注释，它的有效范围是 / * */ 内任意行。

2.3、关于 doc 文档，文档生成命令 javadoc。
2.3.1、首先确定一下 javadoc 能不能正常使用。win + R ---》cmd。

2.3.2、输入 javadoc -help，遇到过 javadoc 不是内部或外部命令的情况。

2.3.3、这时需要把 jdk 的 bin 配置到环境变量 ---》用户变量 ---》PATH 中。
2.3.3.1、此电脑鼠标右键 ---》属性。

2.3.3.2、右侧相关设置 ---》高级系统设置。

2.3.3.3、高级 ---》环境变量。

2.3.3.4、用户变量 ---》Path ---》编辑。

2.3.3.5、新建 ---》填入 jdk\bin 的路径 ---》确定。

2.3.4、环境变量配置完成再输入 javadoc -help，能够输出很多内容就可以了。

2.3.5、生成 doc 文档命令：javadoc 类名.java -encoding utf-8 -charset utf-8。
2.3.6、以 annotation.java 文件进行 doc 文档输出。
2.3.6.1、以下是 annotation.java 文件的内容。

package com.elementaryJava.lesson03;

/**
 * USER:Torres
 * Function:多行注释。
 **/
// annotation 类
public class annotation {
    /*
     * doc 注释：
     * class 前面和方法前面才可以生成 doc 注释。
     * main() 方法，程序的入口。
     */
    public static void main(String[] args) {

        // 输出字符串
        System.out.println("注释的学习");
    }
}

2.3.6.2、annotation 类鼠标右键 ---》Show in Explorer 查看文件所在路径。

2.3.6.3、复制路径。现在路径下的文件只有一个 annotation.java 的文件。

2.3.6.4、win + R ---》cmd。

2.3.6.5、cd 粘贴刚才复制 annotation.java 的路径 ---》d: （切换到 D 盘）---》D:\work\workspace\learnJava\src\com\elementaryJava\lesson03> 路径下输入 javadoc annotation.java -encoding utf-8 -charset utf-8 ---》生成 doc 文档。

C:\Users\86186>cd D:\work\workspace\learnJava\src\com\elementaryJava\lesson03

C:\Users\86186>d:

D:\work\workspace\learnJava\src\com\elementaryJava\lesson03>javadoc annotation.java -encoding utf-8 -charset utf-8
正在加载源文件annotation.java...
正在构造 Javadoc 信息...
标准 Doclet 版本 11.0.11
正在构建所有程序包和类的树...
正在生成.\com\elementaryJava\lesson03\annotation.html...
正在生成.\com\elementaryJava\lesson03\package-summary.html...
正在生成.\com\elementaryJava\lesson03\package-tree.html...
正在生成.\constant-values.html...
正在构建所有程序包和类的索引...
正在生成.\overview-tree.html...
正在生成.\index-all.html...
正在构建所有类的索引...
正在生成.\allclasses-index.html...
正在生成.\allpackages-index.html...
正在生成.\deprecated-list.html...
正在构建所有类的索引...
正在生成.\allclasses.html...
正在生成.\allclasses.html...
正在生成.\index.html...
正在生成.\help-doc.html...

D:\work\workspace\learnJava\src\com\elementaryJava\lesson03>

2.3.6.6、此时，再到目录路径查看一下，会发现多出了很多文件。

2.3.6.7、打开 index.html 文件，可以以网页形式浏览 doc 文档。

2.3.6.8、从上图中点击类进入详情页。这里有说明引用包的路径、类、注释、构造器、方法。从 doc 文档中不难发现程序中 // 开头的单行注释和 /* 开头的多行注释并没有显示出来。只显示了类开头 /** 开头的 doc 文档注释。

2.3.6.9、回到 IDEA 会发现 lesson03 包也多了很多文件，这些文件和文件保存目录下的内容一样。

以上是生成 doc 文档的方法。

2.3.7、已知 /** 开头的 doc 文档注释可以在生成的 doc 文档显示。那么做个试验，在类上面这个区域写 // 开头的单行注释和 /* 开头的多行注释，了解一下 doc 文档输出情况。
2.3.7.1、代码修改一下，类上面用单行注释，Ctrl + S 保存一下，或者 Run 一下看看输出也可以。

package com.elementaryJava.lesson03;

// 这时单行注释 
public class annotation {

    public static void main(String[] args) {

        System.out.println("注释的学习");
    }
}

2.3.7.2、执行 javadoc。

D:\work\workspace\learnJava\src\com\elementaryJava\lesson03>javadoc annotation.java -encoding utf-8 -charset utf-8
正在加载源文件annotation.java...
正在构造 Javadoc 信息...
标准 Doclet 版本 11.0.11
正在构建所有程序包和类的树...
正在生成.\com\elementaryJava\lesson03\annotation.html...
正在生成.\com\elementaryJava\lesson03\package-summary.html...
正在生成.\com\elementaryJava\lesson03\package-tree.html...
正在生成.\constant-values.html...
正在构建所有程序包和类的索引...
正在生成.\overview-tree.html...
正在生成.\index-all.html...
正在构建所有类的索引...
正在生成.\allclasses-index.html...
正在生成.\allpackages-index.html...
正在生成.\deprecated-list.html...
正在构建所有类的索引...
正在生成.\allclasses.html...
正在生成.\allclasses.html...
正在生成.\index.html...
正在生成.\help-doc.html...

2.3.7.3、然后到目录内打开 index.html。

2.3.7.3、点击 annotation 查看详情页。
2.3.7.5、之前有注释的地方，现在已经没有注释了。也可以得出 // 单行注释不会在 doc 文档显示。

2.3.7.6、代码修改一下，类上面用多行注释，Ctrl + S 保存一下，或者 Run 一下看看输出也可以。

package com.elementaryJava.lesson03;

/*
* 这时多行注释
* 这时多行注释
* 这时多行注释
* 这时多行注释
* */
public class annotation {

    public static void main(String[] args) {

        System.out.println("注释的学习");
    }
}

2.3.7.7、执行 javadoc，然后到目录内打开 index.html ---》点击 annotation 查看详情页。得出/* */ 多行注释不会在 doc 文档显示。

以上是在同一区域内分别用 doc 注释、单行注释和多行注释生成 doc 文档。了解 doc 文档对注释的显示情况。

2.3.8、已知 doc 注释能在 doc 文档中显示。那么，程序中 /** 开头的 doc 注释分别用在 annotation 类上面、main 方法上面和 main 方法内。通过对不同区域的 doc 注释，了解一下 doc 文档输出情况。
2.3.8.1、以下修改了 annotation 类的注释。

package com.elementaryJava.lesson03;

/**
 * 类上面的多行注释：
 * USER:Torres
 * Function:多行注释。
 **/
public class annotation {
    /**
     * 方法上面的多行注释：
     * class 前面和方法前面才可以生成 doc 注释。
     * main() 方法，程序的入口。
     */
    public static void main(String[] args) {

        /**
         * main 方法内的多行注释：
         * 输出一段字符串
         */
        System.out.println("注释的学习");
    }
}

2.3.8.2、执行 javadoc，然后到目录内打开 index.html ---》点击 annotation 查看详情页。可以在两个地方找到程序的注释。一个是类 annotation 栏目可以找到类上面的注释，另一个是方法详细资料栏目可以找到方法上面的注释。但找不到 main 方法内的多行注释。通过试验得出，/** 开头的 doc 注释只在类上面和方法上面才会显示。

以上是不同区域分别用 doc 注释生成 doc 文档。了解 doc 文档对注释的显示情况。

三、注释不影响程序运行。

3.1、程序中的注释不会影响程序运行。

package com.elementaryJava.lesson03;

/**
 * 类上面的多行注释：
 * USER:Torres
 * Function:多行注释。
 **/
public class annotation {
    /**
     * 方法上面的多行注释：
     * class 前面和方法前面才可以生成 doc 注释。
     * main() 方法，程序的入口。
     */
    public static void main(String[] args) {
        /**
         * 方法上面的多行注释：
         * class 前面和方法前面才可以生成 doc 注释。
         * main() 方法，程序的入口。
         */
        System.out.println("注释的学习");
    }
}

------------------------------------------------------------------------------
F:\work\java\jdk11\bin\java.exe "-javaagent:F:\work\IDEA-2020\IntelliJ IDEA 2020.1.3\lib\idea_rt.jar=2597:F:\work\IDEA-2020\IntelliJ IDEA 2020.1.3\bin" -Dfile.encoding=UTF-8 -classpath D:\work\workspace\learnJava\out\production\learnJava com.elementaryJava.lesson03.annotation
注释的学习

Process finished with exit code 0