本文讲解 Java 中的注释以及 Javadoc 文档 ~
文章目录
- 1. 注释
- 1.1 引言
- 1.1.1 何为注释？
- 1.1.2 注释有何用？
- 1.1.2.1 方便阅读
- 1.1.2.2 调试程序
- 1.1.3 单行注释和多行注释
- 1.2 方法注释
- 1.2.1 什么是方法注释？
- 1.2.2 如何写方法注释？
- 1.2.3 如何得知被调用方法的注释及位置？
- 1.3 类注释
- 1.3.1 什么是类注释？
- 1.3.2 如何写类注释？
- 2. Javadoc 文档
- 2.1 什么是 Javadoc 文档？
- 2.2 Java 官方文档
- 2.3 如何使用 IDEA 为自己所写的程序生成 Javadoc 文档？
1. 注释
1.1 引言
1.1.1 何为注释？
- 在我看来，注释无非是对一行或多行代码作的解释罢了。它能让读者很快地明白所写代码的含义，好的注释可以极大地增强代码的可读性。以下这段代码是我曾在 C 语言专栏中写下的，学过 C 语言的朋友对这段代码定不陌生，其中的
/* */中的一堆，称为多行注释，//后的那一句称为单行注释，可以根据注释字数的多少选择合适的类型。这些注释都会被编译器忽略，不会执行，仅仅是为了给人看。
1.1.2 注释有何用？
1.1.2.1 方便阅读
- 试试自己多长时间能理解下图中这段代码的含义
- 如果上图中的代码附带了注释，便可一眼看出这段代码的含义。作为一个未来的程序员，写好注释是必备的素养，既方便了自己，也方便了别人
1.1.2.2 调试程序
- 除此之外， 由于注释中的内容不会被编译，所以它还有另外一个实用的功能，就是用来调试程序。举个例子，如果你觉得某段代码可能有问题，可以先把这段代码注释起来，让编译器忽略这段代码，然后再运行。如果程序可以正常执行，则可以说明错误就是由这段代码引起的；反之，如果依然出现相同的错误，则可以说明错误不是由这段代码引起的。在调试程序的过程中使用注释可以缩小错误所在的范围，提高调试程序的效率。
- 在调试中，有时需要给多行代码加上注释，可选中多行代码，然后在键盘上先按下 Ctrl ，再按下 / ，即可加上注释
- 如需给多行代码去掉注释，先选中多行代码，然后在键盘上先按下 Ctrl ，再按下 / ，即可去掉注释
1.1.3 单行注释和多行注释
- Java 中的单行注释一般是先写
//，然后空一格再写内容
- 写多行注释时，可以先打出
/*，按下回车键，*/会自动补全
1.2 方法注释
1.2.1 什么是方法注释？
- 在 C 语言中，写完函数后都会加上注释，便于之后阅读此函数时能迅速地明白该函数的作用
- 在 Java 中，也会为其加上注释，不过函数要改称为方法。除此之外，对方法的注释 Java 也有自己的规范。以下图为例，注释中不仅说明了该方法的作用，也说明了该方法中两个参数的含义及使用此方法后会返回什么
1.2.2 如何写方法注释？
- 以计算两个整形加数和的方法为例，告诉大家方法注释如何去写
- 在方法的上一行输入
/**，按下回车键
- 然后就自动生成了一堆东西，其中 param 的意思是参数，因为方法里有两个参数（
number_a，number_b），所以出现了两个 param ，而 return 在 C 语言里常见，意思是返回值
- 接下来就要自己写了，在空下的第12行中，写出此方法的参数类型及作用。在第13和14行中，写出两个参数的含义。最后在第15行中写出调用此方法后的返回结果
- 点下这个图标，便可以将注释折叠起来
- 再点一下，便可以将注释展开
1.2.3 如何得知被调用方法的注释及位置？
- 在主方法中调用刚创建的求和方法
- 将鼠标移到 sum 上，便可以看到此方法的注释
- 在键盘上按住 Ctrl 键，再点击 sum ，光标还会自动跳到 sum 方法所在的位置
1.3 类注释
1.3.1 什么是类注释？
- 类注释，顾名思义，是加在类上面的注释，是对类的解释。因为类的概念涉及到 Java 的面向对象，所以在这里不解释什么是类，只需知道类注释要写在
public class xxx（xxx 指的是类名）的上方即可，下图红框中的内容就是一个类注释的例子，其中@author后写的是代码的作者，@version后写的是代码的版本，除此之外还有很多，例如：{@code} 、 {@docRoot} 、 @deprecated 、@exception 、{@inheritDoc} 、{@link}等等，但这些目前还不需要知道，所以也不必在意
1.3.2 如何写类注释？
- 在
public class xxx的上一行输入/**，然后按下回车键
- 输入
@author，在后面加上名字，再输入@version，在后面加上版本号 … 这样就写完了一个简单的类注释
2. Javadoc 文档
2.1 什么是 Javadoc 文档？
- Javadoc 是 Sun 公司提供的一种工具，它只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的注释，忽略其他地方的文档注释，然后形成一个和源代码配套的 API 帮助文档。也就是说，只要在编写程序时在文档注释中以一套特定的标签注释，在程序编写完成后，通过 Javadoc 就形成了程序的 API 帮助文档，API 帮助文档相当于产品说明书。（以上解释转载于 https://zhuanlan.zhihu.com/p/599276419）
2.2 Java 官方文档
- Java 作为世界上主流的编程语言之一，其体系十分庞大， 市面上的书很难面面俱到，网络能搜索到的信息也有限，要想深入学习Java，解决一些书上和网络上都难以找到的问题，还是要查看和学习官方文档
2.3 如何使用 IDEA 为自己所写的程序生成 Javadoc 文档？
- 点击 Terminal （Terminal 译为终端）
- 输入：
cd src\com\google\demo（即切换到 Main.java 所在的路径），按下回车键
- 输入：
javadoc -encoding UTF-8 -charset UTF-8 Main.java，按下回车键
- 静待 Javadoc 的生成
- 执行完毕后，可以看到
E:\Project\Java\demo\src\com\google\demo下生成了许多文件如下所示
- 点击 index.html
- 我的电脑里有 Google 浏览器，所以就点了谷歌浏览器对应的图标，即用 Google 浏览器打开 index.html
- 打开便可以看到生成的 Javadoc 文档
- 点击 Main
- 就可以看到 Main.java 的很多信息
- 点击 sum
- 可以看到 sum 方法的具体信息
