如何为我们的程序编写开发文档——Java文档注释

Posted 2021-01-12 张一清

Java文档注释是用于生成Java API文档的注释，通过在程序中的类、属性、方法部分加上注释，就可以用javadoc命令生成漂亮的API文档，是程序员进阶的必备技能。

注意，文档注释只说明紧跟其后的类、属性或者方法。
Javadoc文档生成命令为：

-author和-version可以省略。

根据在文档中显示的效果，文档注释分为三部分。举例如下：

第一部分是简述。如下图中被红框框选的部分:

简述部分写在一段文档注释的最前面，第一个点号 (.) 之前 (包括点号).
第二部分是详细说明部分。该部分对属性或者方法进行详细的说明，雅思周末班在格式上没有什么特殊的要求，可以包含若干个点号。它在文档中的位置如下图所示：

这部分文档对应的代码是：

第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。它在文档中的位置：

标记	范围	作用
@author	类	标明开发该类的作者
@version	类	标明该类模块的版本
@see	类、属性、方法	参考转向，也就是相关主题
@param	方法	对方法中参数的说明
@return	方法	对方法返回值的说明
@exception	方法	对方法可能抛出的异常说明

除上面所写之外，还有javadoc命令等详细参数没有介绍，请自行在命令行中使用help命令查看。
关于生成Java文档，通过命令行进行生成通常只做演示的作用，我们开发所使用的IDE如：IntelliJ IDEA、Eclipse等均集成了文档生成功能，只需要我们把文档注释写好，然后点击按钮即可。