java注释详解_Java文档注释详解

一.javadoc

1.简述

对于Java语言，最体贴的一项设计就是它并没有打算让人们为了写程序而写程序——人们也需要考虑程序的文档化问题。对于程序的文档化，最大的问题 莫过于对文档的维护。若文档与代码分离，那么每次改变代码后都要改变文档，这无疑会变成相当麻烦的一件事情。解决的方法看起来似乎很简单：将代码同文档 “链接”起来。为达到这个目的，最简单的方法是将所有内容都置于同一个文件。然而，为使一切都整齐划一，还必须使用一种特殊的注释语法，以便标记出特殊的 文档；另外还需要一个工具，用于提取这些注释，并按有价值的形式将其展现出来。这些都是Java必须做到的。

用于提取注释的工具叫作javadoc。它采用了部分来自Java编译器的技术，查找我们置入程序的特殊注释标记。它不仅提取由这些标记指示的信息，也将毗邻注释的类名或方法名提取出来。这样一来，我们就可用最轻的工作量，生成十分专业的程序文档。

javadoc输出的是一个HTML文件，可用自己的Web浏览器查看。该工具允许我们创建和管理单个源文件，并生动生成有用的文档。由于有了jvadoc，所以我们能够用标准的方法创建文档。而且由于它非常方便，所以我们能轻松获得所有Java库的文档。

2 具体语法

所 有javadoc命令都只能出现于“/**”注释中。但和平常一样，注释结束于一个“*/”。主要通过两种方式来使用javadoc：嵌入的HTML，或 使用“文档标记”。其中，“文档标记”(Doc tags)是一些以“@”开头的命令，置于注释行的起始处(但前导的“*”会被忽略)。

有三种类型的注释文档，它们对应于位于注释后面的元素：类、变量或者方法。也就是说，一个类注释正好位于一个类定义之前；变量注释正好位于变量定义之前；而一个方法定义正好位于一个方法定义的前面。如下面这个简单的例子所示：

/** 一个类注释 */

public class docTest {

/** 一个变量注释 */

public int i;

/** 一个方法注释 */

public void f() {}

}

注 意javadoc只能为public(公共)和protected(受保护)成员处理注释文档。“private”(私有)和“友好”(详见5章)成员的 注释会被忽略，我们看不到任何输出(也可以用-private标记包括private成员)。这样做是有道理的，因为只有public和 protected成员才可在文件之外使用，这是客户程序员的希望。然而，所有类注释都会包含到输出结果里。

上述代码的输出是一个HTML文件，它与其他Java文档具有相同的标准格式。因此，用户会非常熟悉这种格式，可在您设计的类中方便地“漫游”。设计程序时，请务必考虑输入上述代码，用javadoc处理一下，观看最终HTML文件的效果如何。

3 嵌入HTML

javadoc将HTML命令传递给最终生成的HTML文档。这便使我们能够充分利用HTML的巨大威力。当然，我们的最终动机是格式化代码，不是为了哗众取宠。

注意 ：

在文档注释中，位于一行最开头的星号会被javadoc丢弃。同时丢弃的还有前导空格。

javadoc会对所有内容进行格式化，使其与标准的文档外观相符。

不要将 标题当作嵌入HTML使用，因为javadoc会插入自己的标题，我们给出的标题会与之冲撞。

所有类型的注释文档——类、变量和方法——都支持嵌入HTML。

二.文件输出

三.@标签使用详解

javadoc工具软件识别以下标签：

标签 描述 示例

@author标识一个类的作者@author description

@deprecated指名一个过期的类或成员@deprecated description

{@docRoot}指明当前文档根目录的路径Directory Path

@exception标志一个类抛出的异常@exception exception-name explanation

{@inheritDoc}从直接父类继承的注释Inherits a comment from the immediate surperclass.

{@link}插入一个到另一个主题的链接{@link name text}

{@linkplain}插入一个到另一个主题的链接，但是该链接显示纯文本字体Inserts an in-line link to another topic.

@param说明一个方法的参数@param parameter-name explanation

@return说明返回值类型@return explanation

@see指定一个到另一个主题的链接@see anchor

@serial说明一个序列化属性@serial description

@serialData说明通过writeObject( ) 和 writeExternal( )方法写的数据@serialData description

@serialField说明一个ObjectStreamField组件@serialField name type description

@since标记当引入一个特定的变化时@since release

@throws和 @exception标签一样.The @throws tag has the same meaning as the @exception tag.

{@value}显示常量的值，该常量必须是static属性。Displays the value of a constant, which must be a static field.

@version指定类的版本@version info1.

1.@see 另请参阅

@see 一般用于标记该类相关联的类,@see即可以用在类上，也可以用在方法上(#methodName())。

/***@seecom.my.study.base.Tools*@see#name()*/

public classTest {public voidname() {

}

}

文档显示效果

2.@code： {@code text} 将文本标记为code

@code的使用语法{@code text} 会被解析成text

将文本标记为代码样式的文本，在code内部可以使用 < 、> 等不会被解释成html标签, code标签有自己的样式

一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记。

packagecom.my.study.base;/***

This is a h1 demo!

* {@code

title h1

}

*

*@seecom.my.study.base.Tools

*@see#name()

**/

public classTest {public voidname() {

String name= "Jim";

}

}

3.@param :对参数的描述

一般类中支持泛型时会通过@param来解释泛型的类型

/***

*@paramstr String value*/

public voidname(String str) {

System.out.println(str);

}

4.@author

详细描述后面一般使用@author来标记作者，如果一个文件有多个作者来维护就标记多个@author，@author后面可以跟作者姓名(也可以附带邮箱地址)、组织名称(也可以附带组织官网地址)

5.@link：{@link 包名.类名#方法名(参数类型)} 用于快速链接到相关代码(一般用于描述中)

@link的使用语法{@link 包名.类名#方法名(参数类型)}，其中当包名在当前类中已经导入了包名可以省略，可以只是一个类名，也可以是仅仅是一个方法名，也可以是类名.方法名，使用此文档标记的类或者方法，可用按住Ctrl键+鼠标单击快速跳到相应的类或者方法上，解析成html其实就是使用包名.类名#方法名(参数类型)

/***

This is a h1 demo!

* {@code

title h1

}

*

*

{@linkcom.my.study.base.Tools} class contains many useful tools.

*

*@authorAdministrator

*@authorRooker 7254478@163.com

*

*@seecom.my.study.base.Tools

*@see#name(String)

*

*

**/

6.@since 从以下版本开始

@since 一般用于标记文件创建时项目当时对应的版本，一般后面跟版本号，也可以跟是一个时间，表示文件当前创建的时间

* @since 1.8

* @since 2020-4-29 12:32:35

7.@version 版本

@version用于标记当前版本，默认为1.0

* @version 1.0

8.@return

@return 跟返回值的描述

/***

*@paramstr String value

*@return{@codetrue} if the {@codeCharSequence} is not {@codenull} and has length*/

publicBoolean name(String str) {

System.out.println(str);

String name= str +":";return true;

}

9. pre结合@code使用

{@code

Person[] men=people.stream()

.filter(p-> p.getGender() ==MALE)

.toArray(Person[]::new);

}

10.@throws

@throws 跟异常类型 异常描述 , 用于描述方法内部可能抛出的异常

/***@throwsIllegalArgumentException when the given source contains invalid encoded sequences*/

11.@exception

@exception 用于描述方法签名throws对应的异常

/***@exceptionLoginException if the logout fails.

**/

public boolean logout() throwsLoginException {return false;

}

12.@deprecated

@deprecated 用于标注一个类或成员已过期,通常配合{@link}使用

/***@deprecatedsince 2020-2-29 13:18:58*/

public voidname() {

System.out.println("=================");

}

13@value

{@value} 用于标注在常量上用于表示常量的值

/**默认数量 {@value}*/

private static final Integer QUANTITY = 1;

14.@inheritDoc

@inheritDoc 用于注解在重写方法或者子类上，用于继承父类中的Javadoc

基类的文档注释被继承到了子类

子类可以再加入自己的注释(特殊化扩展)

@return @param @throws 也会被继承

public class SonTest extendsTest {/*** {@inheritDoc}*/

publicBoolean name(String str) {

System.out.println(str);

String name= str + ":";return false;

}

}

windows–>preference

Java–>Code Style–>Code Templates

code–>new Javafiles

编辑它

${filecomment}

${package_declaration}/***@author作者 E-mail:

*@version创建时间：${date} ${time}

* 类说明*/${typecomment}

${type_declaration}

方法二：

通过菜单 Window->Preference 打开参数设置面板，然后选择：

Java -> Code Style -> Code Templates

在右侧选择Comments,将其中的Files项，然后选右边的”Edit”，进入编辑模式：

进入编辑模式后就可以自定义注释了。另外可以插入一些变量，如年、日期等等。

最后，确保 Code -> New javafiles 中有：”${filecomment}”

当然，通过“导出”和“导入”功能，你可以把自己的模板导出来在其他机器上使用。