Java学习day024 文档注释（注释的插入、类注释、方法注释、域注释、通用注释、包与概述注释、注释的抽取）

最新推荐文章于 2022-04-11 14:11:14 发布

Z zehao

最新推荐文章于 2022-04-11 14:11:14 发布

阅读量329

点赞数 1

分类专栏： Java基础学习文章标签： java 编程语言

本文链接：https://blog.csdn.net/Zzehao11/article/details/105249591

版权

Java基础学习专栏收录该内容

105 篇文章 15 订阅

订阅专栏

使用的教材是java核心技术卷1，我将跟着这本书的章节同时配合视频资源来进行学习基础java知识。

day024 文档注释（注释的插入、类注释、方法注释、域注释、通用注释、包与概述注释、注释的抽取）

JDK包含一个很有用的工具，叫做javadoc,它可以由源文件生成一个HTML文档。事实上，之前的的联机API文档就是通过对标准Java类库的源代码运行javadoc生成的。

如果在源代码中添加以专用的定界符/**开始的注释，那么可以很容易地生成一个看上去具有专业水准的文档。这是一种很好的方式，因为这种方式可以将代码与注释保存在一个地方。如果将文档存人一个独立的文件中，就有可能会随着时间的推移，出现代码和注释不一致的问题。然而，由于文档注释与源代码在同一个文件中，在修改源代码的同时，重新运行javadoc就可以轻而易举地保持两者的一致性。

1.注释的插入

javadoc实用程序（utility)从下面几个特性中抽取信息：

•包

•公有类与接口

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

•公有的和受保护的域

应该为上面几部分编写注释、注释应该放置在所描述特性的前面。注释以/**开始，并以*/结束。

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

自由格式文本的第一句应该是一个概要性的句子。javadoc实用程序自动地将这些句子抽取出来形成概要页。

在自由格式文本中，可以使用HTML修饰符，例如，用于强调的<em>...</em>、用于着重强调的<strong>...</strong>以及包含图像的等。不过，一定不要使用或<h1>或<hr>,因为它们会与文档的格式产生冲突。若要键入等宽代码，需使用{@code...}而不是<code>...</code>—这样一来，就不用操心对代码中的<字符转义了。

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} 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
{
    ...
}

然而，大部分IDE提供了自动添加星号*,并且当注释行改变时，自动重新排列这些星号的功能。

3.方法注释

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

•@param变量描述

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

•@return描述

这个标记将对当前方法添加“return”（返回）部分。这个描述可以跨越多行，并可以使用HTML标记。

•©throws类描述

这个标记将添加一个注释，用于表示这个方法有可能抛出异常。下面是一个方法注释的示例：

/**
*Raisesthesalaryofanemployee.
*@parambyPercentthepercentagebywhichtoraisethesalary(e.g.10means10%)
*©returntheamountoftheraise
*/
public double raiseSalary(doublebyPercent)
{
    double raise = salary*byPercent/100;
    salary+=raise;
    returnraise;
}

4.域注释

只需要对公有域（通常指的是静态常量）建立文档。例如,

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

5.通用注释

下面的标记可以用在类文档的注释中。

•@author姓名

这个标记将产生一个**author"(作者）条目。可以使用多个@author标记，每个@author标记对应一个作者。

•©version文本

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

下面的标记可以用于所有的文档注释中。

•@since文本

这个标记将产生一个“since”（始于）条目。这里的text可以是对引人特性的版本描述。例如，©since version1.7.1。

•@deprecated文本

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

例如，

@deprecated Use ,code> setVIsible(true) </code> instead

通过@see和@link标记，可以使用超级链接，链接到javadoc文档的相关部分或外部文档。

•@see引用

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

package.class#feature label
<a href="...">lable/a > 
"text"

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

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

建立一个链接到com.horstmann.corejava.Employee类的raiseSalary(double)方法的超链接。可以省略包名，甚至把包名和类名都省去，此时，链接将定位于当前包或当前类。

需要注意，一定要使用井号（#)，而不要使用句号（.）分隔类名与方法名，或类名与变量名。Java编译器本身可以熟练地断定句点在分隔包、子包、类、内部类与方法和变量时的不同含义。但是javadoc实用程序就没有这么聪明了，因此必须对它提供帮助。

如果@see标记后面有一个<字符，就需要指定一个超链接。可以超链接到任何URL。例如：

@see <a herf = "www.horstmann.com/corejava.html">The Core ]ava home page</a>

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

如果@see标记后面有一个双引号（"）字符，文本就会显示在“see also”部分。

例如，@see"Core Java 2 volume 2"

可以为一个特性添加多个@see标记，但必须将它们放在一起。

•如果愿意的话，还可以在注释中的任何位置放置指向其他类或方法的超级链接，以及插人一个专用的标记

例如，{@link package.class#feature label}。这里的特性描述规则与@see标记规则一样。

6.包与概述注释

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

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

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

还可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为overview,html的文件中，这个文件位于包含所有源文件的父目录中。标记<body>...</body>之间的所有文本将被抽取出来。当用户从导航栏中选择“Overview”时，就会显示出这些注释内容。

7.注释的抽取

这里，假设HTML文件将被存放在目录docDirectory下。执行以下步骤：

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

2)如果是一个包，应该运行命令:

javadoc-d docDirectory nameOfPackage

或对于多个包生成文档，运行:

javadoc-d docDirectory nameOfPackage1 nameOfPackage2...

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

javadoc-d docDirectory*.java

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

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

例如，如果使用命令：

javadoc-link http://docs.oracle.eom/:javase/8/docs/api*.java

那么，所有的标准类库类都会自动地链接到Oracle网站的文档。

如果使用-linksource选项，则每个源文件被转换为HTML(不对代码着色，但包含行编号)，并且每个类和方法名将转变为指向源代码的超链接。

如果需要进一步的定制，例如，生成非HTML格式的文档，可以提供自定义的doclet,以便生成想要的任何输出形式。

Z zehao

关注

1
点赞
踩
1

收藏

觉得还不错? 一键收藏
0
评论
复制链接

分享到 QQ

分享到新浪微博

扫一扫

专栏目录