一、什么是注释?
百度百科解释:注释,是对书籍或文章的语汇、内容、背景、引文作介绍、评议的文字。
二、为什么要在代码中加入注释?
首先,一个软件产品、一份代码的寿命不是在开发完它以后就结束了;比开发更重要的是后续对它的一些扩展(修改);所以,在一个软件的生命周期中,一个人写的代码是会被很多人去阅读、修改的;在别人对你的代码进行阅读、修改时,它们需要知道你当时的思路,了解一些变量的用处;这样才能更加快速的对软件进行维护(PS:对于逻辑复杂点的模块,如果你不加注释,可能过几天你再回头来看,你都不认识你写的是什么)。
其次,注释本身会作为一种文档,与源代码一起交付;如果你开发的是API,使用者需要知道如何调用它,所以你在交付时需要提供API文档;
最后,注释有助于我们在开发时保持思路清晰。
以上纯属个人观点。
三、java中的三种注释形式
1、单行注释:在程序中注释一行代码,java中使用.双斜线(//)放在需要注释的内容之前进行单行注释。
2、多行注释:在程序中注释多行代码,java中使用/*和*/对进行多行注释,将需要注释的内容放在这一对/**/之内即可。
3、文档注释:在程序中对程序中的变量、方法、类、接口进行说明的注释;这类注释可以使用javadoc工具输出到HTML文档中。
四、使用javadoc命令生成API文档
1、javadoc工具的作用:
此命令用于生成API文档,而API文档用于说明类、接口、方法、成员变量的功能,所以,javadoc工具只处理源文件在类、接口、方法、成员变量、构造器和内部类之前的注释,忽略其他地方的注释;而且javadoc工具默认只处理public和protected修饰的类、接口、方法、成员变量、构造器和内部类之前的文档注释,如果需要处理private修饰的内容的注释,需要增加参数-private。
2.使用方法
javadoc 选项 Java源文件|包
选项下面会做介绍;
Java源文件|包支持通配符,如*.java代表当前路径下所有的Java源文件。
3.javadoc工具选项
-d<directory>:该选项指定一个路径,用于将生成的API文档放到指定的目录下;
-windowtitle<text>:该选项指定一个字符串,用于设置API文档的浏览器窗口标题;
-doctitle<html-code>:该选项指定一个HTML格式的文本,用于指定概述页面的标题;
-header<html-code>:该选项指定一个HTML格式的文本,包含每个页面的页眉;
.....................
4.运行结果:
5.javadoc标记
如果希望javadoc生成更为详细的文档信息,则需要在文档注释中计入javadoc标记,常用的javadoc标记如下:
A)能够用于类、接口前的文档注释中的javadoc标记:
@author,@version,@deprecated,@see
注:javadoc默认不提取@author,@version信息,如需提取,则要在javadoc命令后加入 -version -author 参数
B)能够用于构造器或者方法前的文档注释中的javadoc标记:
@see,@deprecated,@param,@return,@exception,@throws
C)能够用于成员变量前的文档注释中的javadoc标记:
@see,@deprecated等
6.关于包描述文件
java的包注释不是放在java类或者接口中的,是由专门的包注释文件——一般名称都为package.html来完成的;该文件与源文件放在一起,javadoc工具会自动提取该文件中<body></body>中的内容作为包的描述信息。