阁楼Java文档注释

2021年1月24日发(作者：落后的英文)
Java
文档注
释

Java
代
码规范

--
注
释


@author LEI
@version 1.10 2005-09-01
1
注
释文档的格式

注
释文档将用来生成
HTML
格式的代
码报告，所以注释文档必须书写在类、域、构造函数、方法、定
义之前。注释文档由两 部分组成
——
描述、
块标记
。

例如：

/**
* The doGet method of the servlet.

* This method is called when a form has its tag value method equals to get.
*
* @param request
* the request send by the client to the server
* @param response
* the response send by the server to the client
* @throws ServletException
* if an error occurred
* @throws IOException
* if an error occurred
*/
public void doGet (HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {

doPost(request, response);
}
前两 行
为描述，描述完毕后，由
@
符号起
头为块标记注视
。

2
注
释的种类

2.1
文件
头注释

文件
头注释以
/*
开始，以
*/
结束，需要注明该文件创 建时间，文件名，命名空间信息
。

例如：

/*
* Created on 2005-7-2
* /
2.2
类、接口注释

类、接口
的注
释采用

/** … */
，描述部分用来< br>书写该类的作用或者相关信息，块标记部分必须注明作
者和版本
。

例如：

/**Title: XXXX DRIVER 3.0
*Description: XXXX DRIVER 3.0
*Copyright: Copyright (c) 2003
*Company:XXXX
有限公司

*
* @author Java Development Group
* @version 3.0
*/
例如：

/**
* A class representing a window on the screen.
* For example:
*
* Window win = new Window(parent);
* ();
*
*
* @author Sami Shaio
* @version %I%, %G%
* @see ndow
* @see
*/
class Window extends BaseWindow {
...
}
2.3
构造函数注
释

构造函数注
释采用

/** … */
，描述部分注明构造函数的作用，不一定有
块标记部分
。

例如：

/**
*
默
认构造函
数

*/
有例如：

/**
*
带参数构造函数
,
初始化模式名
,
名称和数据源
类
型

*
* @param schema
* Ref
模式名

* @param name
* Ref
名称

* @param type
* byVal
数据源
类
型

*/
2.4
域注
释

域注
释可以出现在注释文档里面，也可以不出现在注释文档里面。用
/** … */
的域注
释将会被认为是
注释文档热出现在最终生成的
HTML
报告里 面，而使用
/* … */
的注
释会被忽略
。

例如：

/*
由于
triger
和表用一个
DM Source
，所以要区分和表的迁移成功
标记
*/
boolean isTrigerSuccess = false;
又例如：

/**
由于
triger
和表用一个
DMSource
，所以要区分和表的迁移成功
标记
*/
boolean isTrigerSuccess = false;
再例如：

/**
* The X-coordinate of the component.
*
* @see #getLocation()
*/
int x = 1263732;

2.5
方法注
释

方法注
释采用

/** … */
，描述部分注明方法的功能，块标记部分注明方法的参数，返回值，异常等信
息。例如
：

/**
*
设置是否有外码约
束

*
* @param conn
* Connection
与数据
库的连
接

*/
2.6
定
义注释

规则同域注释
。

3
注
释块标记

3.1
标记的顺序

块标记将采用如下顺序
：

…

*
* @param (classes, interfaces, methods and constructors only)
* @return (methods only)
* @exception (@throws is a synonym added in Javadoc 1.2)
* @author (classes and interfaces only, required)
* @version (classes and interfaces only, required. See footnote 1)
* @see
* @since
* @serial (or @serialField or @serialData)
* @deprecated (see How and When To Deprecate APIs)
* …

一个
块标记可以根据需要重复出现多次，多次出现的标记按照如下顺序
：

@author
按照
时间先后顺序（
chronological
）

@param
按照参数定
义顺序（
declaration
）

@throws
按照异常名字的字母
顺序（
alphabetically
）

@see
按照如下
顺序
：

@see #field
@see #Constructor(Type, Type...)
@see #Constructor(Type id, Type id...)
@see #method(Type, Type,...)
@see #method(Type id, Type, id...)
@see Class
@see Class#field
@see Class#Constructor(Type, Type...)
@see Class#Constructor(Type id, Type id)
@see Class#method(Type, Type,...)
@see Class#method(Type id, Type id,...)
@see
@see #field
@see #Constructor(Type, Type...)
@see #Constructor(Type id, Type id)
@see #method(Type, Type,...)
@see #method(Type id, Type, id)
@see package
3.2
标记介绍

3.2.1 @param
标记

@param
后面空格后跟着参数的
变量名字（不是类型），空格后跟着对该参数的描 述
。

在描述中第一个名字
为该变量的数据类型，表示数据类型的名次前面可 以有一个冠词如：
a,an,the
。
如果是
int
类型的参数则不 需要注明数据类型。例如
：

…

* @param ch the char
用用来
……

* @param _image the image
用来
……

* @param _num
一个数字
……

…

对于参数的描述如果只是一短语，最好不要首字母大写，结尾也不要句号
。

对于参数的描述是一个句子，最好不要首字母大写，如果出现了句号这说明你的描述不止一句话。如
果非 要首字母大写的话，必须用句号来结束句子。（英文的句号
）

公司内部添加
ByRef
和
ByVal
两个
标记，例如
：

* @param _image the image ByRef
用来
……

说明该参数是引用传递（指针），
ByVal
可以省略，表示是
值传递
。< br>
3.2.2 @return
标记

返回
为空（void
）的构造函数或者函数，
@return
可以省略。

如果返回
值就是输入参数，必须用与输入参数的
@param
相同的描述信息。

必要的
时候注明特殊条件写的返回值
。

3.2.3 @throws
标记

@throws
以前使用的是
@exception
。

@ throws
的内容必
须在函数的
throws
部分定
义
。

3.2.4 @author
标记

类注释标记
。