JavaDoc详解：注释、标记与工具使用指南-优快云博客

我们程序员们在项目开发过程中，使用Java的文档注释是我们必修的一门课程。文档注释提供将程序信息嵌入程序的功能，开发者可以使用javadoc工具将信息取出。

前言：我们在开发项目过程中将文档注释使用javadoc工具取出，然后转换成Html文档。文档注释提供了编写程文档的便捷方式；javadoc工具生成的文档几乎每个开发者都看到过；但是有一些标记可是不是太理解。今天给大家分享一个比较全面的Java文档注释列表；点赞关注加收藏，别下次找不到啦~

javadoc实用程序标记列表：

Tag标记	意义
@author	确定类的作者
@deprecated	指示反对使用这个类或成员
{@docRoot}	指定当前文档的根目录路径 (Java 2的1.3版新增)
@exception	确定一个方法引发的异常
{@link}	插入对另一个主题的内部链接
@param	为方法的参数提供文档
@return	为方法的返回值提供文档
@see	指定对另一个主题的链接
@serial	为默认的可序列化字段提供文档
@serialData	为writeObject( )或者writeExternal( )方法编写的数据提供文档
@serialField	为ObjectStreamField组件提供文档
@since	当引入一个特定改变时，声明发布版本
@throws	与@exception相同
@version	指定类的版本

以上标红字段是项目中常见的。

在一个文档注释中，也可以使用其它的标准html标记。然而，一些标记（如标题）是不能使用的，因为它们会破坏由javadoc生成的html文档外观。

可以使用文档注释为类、接口、域、构造函数和方法提供文档。在所有这些情况中，文档注释必须紧接在被注释的项目之前。

下面详细列出了每个标记的使用方法：

@ author

标记@author 指定一个类的作者，它的语法如下：

@author description

其中， description 通常是编写这个类的作者名字。标记@author 只能用在类的文档中。在执行javadoc时，你需要指定-author 选项，才可将@author 域包括在HTML文档中。

@deprecated

@deprecated 标记指示不赞成使用一个类或是一个成员。建议使用@see 标记指示程序员其他可用的选择。其语法如下：

@deprecated description

其中description 是描述反对的信息。由@deprecated 标记指定的信息由编译器识别，包括在生成的.class文件中，因此在编译Java源文件时，程序员可以得到这个信息。@deprecated 标记可以用于变量，方法和类的文档中。

{@docRoot}

{@docRoot}指定当前文档的根目录路径。

@exception

@exception 标记描述一个方法的异常，其语法如下：

@exception exception-name explanation

其中，异常的完整名称由exception-name指定，explanation 是描述异常如何产生的字符串。@exception 只用于方法的文档。

{@link}

{@link} 标记提供一个附加信息的联机超链接。其语法如下：

{@link name text}

其中，name 是加入超链接的类或方法的名字， text 是显示的字符串。

@param

@param 标记注释一个方法的参数。其语法如下所示：

@param parameter-name explanation

其中parameter-name指定方法的参数名。这个参数的含义由explanation描述。@param 标记只用在方法的文档中。

@return

@return 标记描述一个方法的返回值。其语法如下：

@return explanation

其中，explanation 描述方法返回值的类型和含意。@return 标记只用在方法的文档中。

@see

@see 标记提供附加信息的引用。最常见的使用形式如下所示：

@see anchor
@see pkg.class#member text

在第一种格式中，ancho 是一个指向绝对或相对URL的超链接。第二种格式，pkg.class#member 指示项目的名字，text是项目的文本显示。文本参数是可选的，如果不用，显示pkg.class#membe 指定的项目。成员名，也是可选的。因此，除了指向特定方法或者字段的引用之外，你还可以指定一个引用指向一个包，一个类或是一个接口。名字可以是完全限定的，也可以是部分限定的。但是，成员名（如果存在的话）之前的点必须被替换成一个散列字符。