您的位置：首页 > 编程语言 > Java开发

Java复习笔记(4)——文档注释

2016-09-09 13:38 465 查看
Java中有3种书写注释的方式

// 行注释，从开始到本行结尾。

/* ... */ 长篇注释

/** ... */ 可生成文档的注释。

1、使用javadoc工具可以由源文件产生HTML文档。

2、javadoc抽取信息范围：

·包

·公有类与接口

·公有的和受保护的域

·公有的和受保护的构造器及方法。

3、每个/**...
*/文档注释在标记之后紧跟着自由格式文本(free-form
text)，标记由@开始，如：@author或@param。

4、自由格式文本中可以使用HTML修饰符，例如：用于强调的<em>
... </em>、用于设置登宽“打字机”字体的<code>
... </code>、用于强调的<strong>...</strong>以及包含图像的<img...>等。

5、类注释：必须放在import语句之后、类定义之前。(没有必要在每一行的开始都用星号)。

6、方法注释：必须放在所述方法之前，除了通用标记外，还可以使用下面的标记：

·@param

这个标记将对当前方法的参数部分添加一个条目。这个描述可以占据多行，并可以使用HTML标记。一个方法的所有@param标记必须放在一起。

·@return

这个标记对当前方法的返回值进行描述。这个描述可以跨越多行，可以施工HTML标记。

·@throws

这个标记描述方法可能抛出有的异常。

7、域注释：只需要对共有域(通常指的是静态常量)建立文档。

8、通用注释：下面的标记可以用在类文档的注释中：

·@author

这个标记产生一个“author”(作者)条目。可以使用多个@author标记，每个@author标记对应一个作者。

·@version

这个标记将产生一个“version”(版本)条目。这里的文本可以是对当前版本的任何描述。

下面的标记可以用在所有的文档注释中：

·@since

这个标记将产生一个“since”(始于)条目。这里的文本可以是对引入特性的版本描述。例如：@since
version 1.7.1

·@deprecated

这个标记将对类、方法或变量添加一个“不再使用”的注释。文本给出了取代的建议。例如：

@deprecated Use <code> setvisible(true) </code> instead.

·@see

这个标记将在“see
also”部分添加一个超链接。它可以用于类中，也可以用于方法中。这里的引用可以选择下列情形之一：

package.class#feature label

<a href = “...”>
label </a>

“text”

第一种情况是最常见的。只要提供类、方法或变量的名字，javadoc就在文档中插入一个超链接。如果省去包名和类名，此时链接将定位于当前包或当前类。

第二种情况为指定一个超链接。这种情况可以链接到任何URL。例如：

@see <a href=”www.horstmann.com/corejava.html”>The
Core Java home page </a>

在上述各种情况下、都可以指定一个可选的标签(label)作为链接锚(link
anchor)。如果省略了label，用户看到的锚的名称就是目标代码名或URL。

还可以在注释中的任何为止放置指向其他类或方法的超级链接，以及插入一个专用的标记，例如：

{@link package.class#feature label}

这里的描述规则与@see标记规则一样。

9、包注释：要想产生包注释、需要在包目录中添加一个单独的文件。可以有如下两个选择：

(1) 提供一个package.html命名的HTML文件，在标记<body>...</body>之间的所有文本都会被抽取出来。

(2) 提供一个以package-info.java命名的Java文件，这个文件必须包含一个初始的以/**和*/界定的Javadoc注释，跟在一个包语句之后。它不应该包含更多的代码或注释。

10、概述注释：还可以为所有的源文件提供一个概述性的注释。这个注释必须放置在一个名为overview.html的文件中，这个文件位于包含所有源文件的父目录中。标记<body>...</body>中的所有文本将被抽取出来。

11、注释的抽取步骤如下：

(1) 切换到包含想要生成文档的源文件目录。如果有嵌套的包要生成文档，就必须切换到根目录(如果存在overview.html文件的话，这也是它所在的目录)。

(2) 如果是一个包应该运行命令：

javadoc -d dicDirectory nameOfPackage

如果对于多个包生成文档，运行：

javadoc -d docDirectory nameofPackage1 nameofPackage2 ...

如果文件在默认包中，就应该运行：

javadoc -d docDirectory *.java

如果省略了-d
docDirectory选项，那HTML问加你就会被提取到当前目录下。这样就有可能会带来混乱，因此不提倡这种做法。

-version 选项在文档中包含@author和@version标记(默认情况下，这些标记会被省略)。另一个有用的选项是-link，用来为标准类添加超链接。例如：如果使用命令：

javadoc -link http://docs.oracle.com/javase/7/docs/api *.java

那么，所有的编著类库都会自动地连接到Oracle网站的文档。

如果使用-linksource选项，则每个源文件被转换为HTML(不对代码着色，但包含行编号)，并且每个类和方法名将转变为指向源代码的超链接。 
内容来自用户分享和网络整理，不保证内容的准确性，如有侵权内容，可联系管理员处理 点击这里给我发消息
标签：  Java基础 注释
相关文章推荐
新的分享
章节导航