java中注释的编写——javadoc

**

java中注释的编写——javadoc

**
当我们查看java中的源代码时第一眼我们会觉得它特别严谨和
词语解释：javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。

主要有以下这几类：

首先你要写的便是/**
在这 之后，第一行或几行是关于类、变量和方法的主要描述。
之后，你可以包含一个或多个各种各样的 @ 标签。每一个 @ 标签必须在一个新行的开始或者在一行的开始紧跟星号(*).
多个相同类型的标签应该放成一组。例如，如果你有三个 @see 标签，可以将它们一个接一个的放在一起。

写在类上的javadoc一般可以分为三段
第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束
第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束
第三段：文档标注，用于标注作者、创建时间、参阅类等信息

第一段：概要描述

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

@link的使用语法{@link 包名.类名#方法名(参数类型)}，其中当包名在当前类中已经导入了包名可以省略，可以只是一个类名，也可以是仅仅是一个方法名，也可以是类名.方法名，使用此文档标记的类或者方法，可用通过按住Ctrl键+单击 可以快速跳到相应的类或者方法上。
使用举例：
// 完全限定的类名
{@link java.lang.Character}

// 省略包名
{@link String}

// 包名.类名.方法名(参数类型)
{@link java.lang.String#charAt(int)}

2. @code： {@code text} 将文本标记为code
   {@code text} 会被解析成 text

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

第二段：详细描述
详细描述一般用一段或者几个锻炼来详细描述类的作用

3.@see 另请参阅
@see 一般用于标记该类相关联的类,@see即可以用在类上，也可以用在方法上。

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

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

写在方法上的Javadoc也分为三段
第一段：概要描述，通常用一句或者一段话简要描述该方法的作用，以英文句号作为结束
第二段：详细描述，通常用一段或者多段话来详细描述该方法的作用，一般每段话都以英文句号作为结束
第三段：文档标注，用于标注参数、返回值、异常、参阅等