5.Java中的注释及Javadoc文档

本文讲解 Java 中的注释以及 Javadoc 文档 ~

---

1. 注释

1.1 引言

1.1.1 何为注释？

• 在我看来，注释无非是对一行或多行代码作的解释罢了。它能让读者很快地明白所写代码的含义，好的注释可以极大地增强代码的可读性。以下这段代码是我曾在 C 语言专栏中写下的，学过 C 语言的朋友对这段代码定不陌生，其中的 /* */ 中的一堆，称为多行注释，// 后的那一句称为单行注释，可以根据注释字数的多少选择合适的类型。这些注释都会被编译器忽略，不会执行，仅仅是为了给人看。
  

1.1.2 注释有何用？

1.1.2.1 方便阅读

1. 试试自己多长时间能理解下图中这段代码的含义
   
2. 如果上图中的代码附带了注释，便可一眼看出这段代码的含义。作为一个未来的程序员，写好注释是必备的素养，既方便了自己，也方便了别人
   

1.1.2.2 调试程序

• 除此之外， 由于注释中的内容不会被编译，所以它还有另外一个实用的功能，就是用来调试程序。举个例子，如果你觉得某段代码可能有问题，可以先把这段代码注释起来，让编译器忽略这段代码，然后再运行。如果程序可以正常执行，则可以说明错误就是由这段代码引起的；反之，如果依然出现相同的错误，则可以说明错误不是由这段代码引起的。在调试程序的过程中使用注释可以缩小错误所在的范围，提高调试程序的效率。
• 在调试中，有时需要给多行代码加上注释，可选中多行代码，然后在键盘上先按下 Ctrl ，再按下 / ，即可加上注释
• 如需给多行代码去掉注释，先选中多行代码，然后在键盘上先按下 Ctrl ，再按下 / ，即可去掉注释
  

1.1.3 单行注释和多行注释

• Java 中的单行注释一般是先写 // ，然后空一格再写内容
  
• 写多行注释时，可以先打出 /* ，按下回车键，*/ 会自动补全
  

1.2 方法注释

1.2.1 什么是方法注释？

1. 在 C 语言中，写完函数后都会加上注释，便于之后阅读此函数时能迅速地明白该函数的作用
   
2. 在 Java 中，也会为其加上注释，不过函数要改称为方法。除此之外，对方法的注释 Java 也有自己的规范。以下图为例，注释中不仅说明了该方法的作用，也说明了该方法中两个参数的含义及使用此方法后会返回什么
   

1.2.2 如何写方法注释？

1. 以计算两个整形加数和的方法为例，告诉大家方法注释如何去写
   
2. 在方法的上一行输入 /** ，按下回车键
   
3. 然后就自动生成了一堆东西，其中 param 的意思是参数，因为方法里有两个参数（number_a，number_b），所以出现了两个 param ，而 return 在 C 语言里常见，意思是返回值
   
4. 接下来就要自己写了，在空下的第12行中，写出此方法的参数类型及作用。在第13和14行中，写出两个参数的含义。最后在第15行中写出调用此方法后的返回结果
5. 点下这个图标，便可以将注释折叠起来
   
6. 再点一下，便可以将注释展开
   

1.2.3 如何得知被调用方法的注释及位置？

1. 在主方法中调用刚创建的求和方法
   
2. 将鼠标移到 sum 上，便可以看到此方法的注释
   
3. 在键盘上按住 Ctrl 键，再点击 sum ，光标还会自动跳到 sum 方法所在的位置
   

1.3 类注释

1.3.1 什么是类注释？

• 类注释，顾名思义，是加在类上面的注释，是对类的解释。因为类的概念涉及到 Java 的面向对象，所以在这里不解释什么是类，只需知道类注释要写在 public class xxx （xxx 指的是类名）的上方即可，下图红框中的内容就是一个类注释的例子，其中 @author 后写的是代码的作者，@version 后写的是代码的版本，除此之外还有很多，例如：{@code} 、 {@docRoot} 、 @deprecated 、@exception 、{@inheritDoc} 、{@link} 等等，但这些目前还不需要知道，所以也不必在意
  

1.3.2 如何写类注释？

1. 在 public class xxx 的上一行输入 /** ，然后按下回车键
   
2. 输入 @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 文档？

1. 点击 Terminal （Terminal 译为终端）
   
2. 输入：cd src\com\google\demo（即切换到 Main.java 所在的路径），按下回车键
   
3. 输入：javadoc -encoding UTF-8 -charset UTF-8 Main.java，按下回车键
   
4. 静待 Javadoc 的生成
   
5. 执行完毕后，可以看到 E:\Project\Java\demo\src\com\google\demo 下生成了许多文件如下所示
   
6. 点击 index.html
   
7. 我的电脑里有 Google 浏览器，所以就点了谷歌浏览器对应的图标，即用 Google 浏览器打开 index.html
   
8. 打开便可以看到生成的 Javadoc 文档
   
9. 点击 Main
   
10. 就可以看到 Main.java 的很多信息
    
11. 点击 sum
    
12. 可以看到 sum 方法的具体信息