第2章番外2 令人惊喜的注释文档

Java沿用了C++的注释风格,用//进行单行注释,用/**/进行多行代码的注释,有时候多行注释中间的每一行开头会有一个*,但本质上是一样的。

下面是多行注释的两种形式:

/*Thisisacomment

*thatcontinues

*acrosslines

*/

/*Thisisacommentthat

continuesacrosslines*/

注释文档:

Java带给我最大的惊喜还是它的注释文档,注释文档的出现将代码和文档链接起来,为我们免去了编写修改文档的麻烦,而且生成的HTML文档格式也是美cry的。

javadoc:

javadoc就是用于提取注释生成文档的工具,它是JDK的一部分。Javadoc不仅整合注释里的信息,还把相邻的类名或者方法名提取出来,让我们用最小的力气生成好看的文档。

生成方式:

1.命令行:

javadoc-d文档存放目录-author-version源文件名.java

这条命令编译一个名为"源文件名.java"的java源文件,并将生成的文档存放在"文档存放目录"指定的目录下,生成的文档中index.html就是文档的首页。-author和-version两个选项可以省略。

2.Eclipse可以直接导出。

注释语法:

使用javadoc的方式有两种:嵌入HTML和文档标签。

“独立文档标签”:以“@”字符开头,“@”字符要置于注释行的最前面

“行内文档标签”:以“@”字符开头,可以出现在javadoc注释中的任何地方,但要在花括号内。

正如下面的例子:

/**Aclasscomment*/

publicclassDocTest{

/**Avariablecomment*/

publicinti;

/**Amethodcomment*/

publicvoidf(){}

}

注意,javadoc只能为public和protected成员进行文档注释。private和包内可访问成员的注释会被忽略掉。不过可以用-private进行标记,以便对private成员一并处理。

HTML命令重新嵌入格式化的就不说了,原来的格式已经足够好了。

标签示例:

1.@see:引用其他类

@see标签允许你引用其他类的文档。javadoc会在其生成的HTML文件中,用@see标签链接到其他文档。格式如下:

@seeclassname

@seefully-qualified-classname

@seefully-qualified-classname#method-name

每种格式都会在生成的文档中加入一个具有超链接的“SeeAlso”条目。但是javadoc不会

检查你所提供的超链接是否有效。

2.{@linkpackage.class#memberlabel}

该标签与@see极其相似,只是它可以用于行内,并且是用“label”作为超链接文本而不用

“SeeAlso”。

3.{@docRoot}

该标签产生到文档根目录的相对路径,用于文档树页面的显式超链接。

4.{@inheritDoc}

该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。

5.@version

该标签的格式如下:

@versionversion-information

其中,“version-information”可以是任何你认为适合作为版本说明的重要信息。如果javadoc

命令行使用了“-version”标记,那么就可以从生成的HTML文档中提取出版本信息。

6.@author

该标签的格式如下:

@authorauthor-information

其中,“author-information”,望文生义你也知道,应该是你的姓名,也可以包括电子邮件

地址或者其他任何适宜的信息。如果javadoc命令行使用了“-author”标签,那么就可以从生成的HTML文档中提取作者信息。

可以使用多个标签,以便列出所有作者,但是它们必须连续放置。全部作者信息会合并到

同一段落,置于生成的HTML中。

7.@since

该标签允许你指定程序代码最早使用的版本,你将会在HTMLJava文档中看到它被用来指

定所用的JDK版本。

8.@param

该标签用于方法文档中,形式如下:

@paramparameter-namedescription

绊脚石乃是进身之阶。

第2章番外2 令人惊喜的注释文档

相关文章:

你感兴趣的文章:

标签云: