4.9 文档注释

最新推荐文章于 2023-12-15 09:00:00 发布

Jie Han

最新推荐文章于 2023-12-15 09:00:00 发布

阅读量200

点赞数

分类专栏： Java核心卷I---摘抄文章标签： java

原文链接：https://blog.csdn.net/z__csdn/article/details/111144517

版权

Java核心卷I---摘抄专栏收录该内容

13 篇文章 0 订阅

订阅专栏

文章目录

4.9 文档注释

4.9 文档注释

JDK包含一个很有用的工具，叫做javadoc，它可以由源文件生成一个HTML文档。事实上，在第三章介绍的联机API文档就是通过对标准java类库的源代码运行javadoc生成的。
如果在源代码中添加以特殊定界符/**开始的注释，你可以很容易地生成一个看上去具有专业水平的文档。这是一种很好的方法，因为这样可以将代码与注释放在同一个地方。如果将文档存放在一个独立的文件中，就有可能会随着时间的推移出现代码和注释不一致的问题。然而，由于文档注释与源代码在同一个文件中，在修改源码的同时，重新运行javadoc就可以轻而易举地保持两者的一致性。

4.9.1 注释的插入

javadoc 实用工具从下面几项中抽取信息：

模块
包
公共类与接口
公共的和受保护的字段
公共的和受保护的构造器及方法

在第五章将介绍保护特性。第六章将介绍接口，模块在卷二的第九章介绍。
可以，并且我们应该为以上各个特性编写注释。注释放置在所描述特性的前面。注释以/*开始，并以/结束。

每个/**…*/文档注释包含标记以及之后紧跟着的自由格式文本。标记以@开始，如@since或@param。
自由格式文本的第一句应该是一个概要性的句子。javadoc工具自动地将这些句子抽取出来生成概要页。
在自由格式文本中，可以使用HTML修饰符，例如，用于强调的<em>...</em>、用于着重强调的<strong>...</strong>、用于项目符号列表的<ul>/<li>以及用于包含图像的<img ...>等。要键入等宽代码，需要使用{@code…}而不是<code>...</code> ——这样一来，就不用操心对代码中的<字符转义了。
注释：如果文档中有到其他文件的链接，比如，图像文件。例如，图表或者用户界面组件的图像，就应该将这些文件放到包含源文件的目录下的一个子目录doc-files中。javadoc工具将从源目录将doc-files目录及其内容拷贝到文档目录中。在链接中需要使用doc-files目录，例如：

<img src="doc-files/uml.png" alt="UML diagram"/>

4.9.2 类注释

类注释必须放在import语句之后，类定义之前。
例子：

/**
	* A {@code Card} object represents a playing card, such
	* as "Queen of Hearts". A card has a suit (Diamond,Heart,
	* Spade or Club) and a value (1=Ace,2...10,11=Jack,
	* 12=Queen,13=King)
*/
public class card{
	...
}

注释：没有必要在每一行的开始都添加星号，例如，以下的同样是合法的：

/**
	A <code>Card</code> object represents a playing card, such
	as "Queen of Hearts". A card has a suit (Diamond,Heart,
	Spade or Club) and a value (1=Ace,2...10,11=Jack,
	12=Queen,13=King)
*/

不过，大部分IDE会自动提供星号，而且换行改变时，还会重新放置星号。

4.9.3 方法注释

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

@param variable description 这个标记将给当前方法的parameters参数部分增加一个条目。这个描述可以占据多行，并且可以使用HTML标记。一个方法的所有@param标记必须放在一起。
@return description 这个标记将给当前方法添加returns返回部分。这个描述可以跨多行，并且可以使用HTML标记。
@throws class description 这个标记将添加一个注释，表示这个方法有可能抛出异常。有关异常的详细内容将在第七章讨论。

下面是一个方法注释的示例：

/**
	* Raises the salary of an employee.
	* @param byPercent the percentage by which to raise raise the salary (e.g.,10 means 10%)
	* @return the amount of the raise
*/
public double raiseSalary(double byPercent){
	double raise = salary*byPercent/100;
	salary=salary+raise;
	return raise;
}

4.9.4 字段注释

只需要对公共字段（通常指的是静态常量）建立文档。例如：

/**
	* The "Hearts" card suit
*/
public static final int HEARTS=1;

4.9.5 通用注释

标记@since text 会建立一个“since（始于）”条目。text（文本）可以是引入这个特性的版本的任何描述。例如，@since 1.7.1。
下面的标记可以用在类文档注释中。

@author name 这个标记将产生一个“author（作者）”条目。可以使用多个@author标记，每个@author标记对应一个作者。并不是非得使用这个标记，你的版本控制系统能够更好地跟踪作者。
@version text 这个标记将产生一个“version”（版本）条目。这里的文本可以是对当前版本的任何描述。

通过@see和@link标记，可以使用超链接，链接到javadoc文档的相关部分或外部文档。
标记@see reference 将在“see also”（参见）部分增加一个一个超链接。它可以用于类中。也可以用于方法中。这里的reference(
引用)可以有以下选择：

package.class#feature label
html <a href="...">label</a>
“text”

第一种情况是最有用的。只要提供类、方法或者变量的名字，javadoc就在文档中插入一个超链接。例如：

@see com.horstmann.corejava.Employee#raiseSalary(double)

这会建立一个链接到com.horstmann.core.Employee类的raiseSalary(double)方法的超链接。可以省略包名，甚至把包名和类名都省去，这样一来，就会位于当前包或者当前类中。
需要注意，一定要使用井号#，而不要使用句号（ . ）分隔类名与方法名，或类名与变量名。Java编译器自身可以熟练地确定句点在分隔包、子包、类、内部类与方法和变量时的不同含义。但是，javadoc工具就不是这么聪明的，因此必须对它提供帮助。
如果@see 标记后面有一个<字符，就需要指定一个超链接。可以链接到任何URL。例如：

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

在上述各种情况下，都可以指定一个可选的标签（label）作为链接锚（link anchor）。如果省略了标签，用户看到的锚就是目标代码名或URL。
如果@see 标记后面有一个双引号（"）字符，文本就会显示在"see also"部分。例如，

@see "Core Java 2 volume 2"

可以为一个特性添加多个@see标记，但必须将它们放在一起。
如果愿意，还可以在文档注释中的任何位置放置指向其他类或方法的超链接。可以在注释中的任何位置插入一个形式如下的特殊标记：

{@link package.class#feature label}

这里的特性描述规则与@see标记使用的规则相同。
最后，在Java 9中，还可以使用@index entry标记为搜索框增加一个条目。

4.9.6 包注释

可以直接将类、方法和变量的注释放置在Java源文件中，只要用/**…*/文档注释界定就可以了。但是，要想产生包注释，就需要在每一个包目录中添加一个单独的文件。可以有如下两个选择：

提供一个名为package-info.java的Java文件。这个文件必须包含一个初始的以/*和/界定的javadoc注释，后面是一个package语句。他不能包含更多的代码或注释。
提供一个名为package.html的HTML文件。会抽取标记<body>...<body>之间的所有文本。

4.9.7 注释抽取

在这里，假设你希望HTML文件将放在名为docDirectory的目录下。执行以下步骤：

切换到包含想要生成文档的源文件的目录。如果有嵌套的包要生成文档，例如 com.horstmann.corejava ，就必须切换到包含子目录com的目录。（如果提供了overview.html文件的话，这就是这个文件所在的目录）。
如果是一个包，应该运行命令：

javadoc -d docDircetory nameOfPackage

或者如果要为多个包生成文档，运行：

javadoc -d docDirectory nameOfPackage1 nameOfPackage2 ...

如果文件在无名的包中，运行：

javadoc -d docDriectory *.java

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

可以使用很多命令行选项对javadoc程序进行优化。例如，可以使用-author和-version选项在文档中包含@author和@version标记。（默认情况下这些标记会被省略）。另一个很有用的选项是-link，用来为标准类添加超链接。例如，如果使用命令：

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

那么，所有的标准类库类都会自动的链接到Oracle网站的文档。
如果使用 -linksource 选项，每个源文件都会转换为HTML，并且每个类和方法名将变为指向源代码的超链接。
还可以为所有的源文件提供一个概要注释。把它放在一个类似overview.html的文件中，运行javadoc工具，并提供命令行选项:
-overview filename 。
将抽取标记<body>...</body>之间的所有文本。当用户从导航栏中选择“Overview”时，就会显示出这些内容。
有关其他的选项，请查阅javadoc工具的联机文档。

Jie Han

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
4.9 文档注释

4.9 文档注释JDK包含一个很有用的工具，叫做javadoc，它可以由源文件生成一个HTML文档。事实上，在第三章介绍的联机API文档就是通过对标准java类库的源代码运行javadoc生成的。如果在源代码中添加以特殊定界符/**开始的注释，你可以很容易地生成一个看上去具有专业水平的文档。这是一种很好的方法，因为这样可以将代码与注释放在同一个地方。如果将文档存放在一个独立的文件中，就有可能会随着时间的推移出现代码和注释不一致的问题。然而，由于文档注释与源代码在同一个文件中，在修改源码的同时，重新运行j
复制链接

扫一扫