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

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

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

-author和-version可以省略。

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

第一部分是简述。如下图中被红框框选的部分:
如何为我们的程序编写开发文档——Java文档注释

简述部分写在一段文档注释的最前面,第一个点号 (.) 之前 (包括点号).

第二部分是详细说明部分。该部分对属性或者方法进行详细的说明,雅思周末班在格式上没有什么特殊的要求,可以包含若干个点号。它在文档中的位置如下图所示:

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

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

第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。它在文档中的位置:
如何为我们的程序编写开发文档——Java文档注释

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

除上面所写之外,还有javadoc命令等详细参数没有介绍,请自行在命令行中使用help命令查看。

关于生成Java文档,通过命令行进行生成通常只做演示的作用,我们开发所使用的IDE如:IntelliJ
IDEA、Eclipse等均集成了文档生成功能,只需要我们把文档注释写好,然后点击按钮即可。

上一篇:Sublime Text3如何快速预览html文件


下一篇:用asp.net c# HttpWebRequest获取网页源代码