Java注释

类、接口的注释采用 /** … */，描述部分用来书写该类的作用或者相关信息，块标记部分必须注明作者和版本。
例如：
/**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);
* win.show();
*
*
* @author Sami Shaio
* @version %I%, %G%
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}

 

 

 

-----------------------------------------------------------

 

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 类、接口注释
类、接口的注释采用 /** … */，描述部分用来书写该类的作用或者相关信息，块标记部分必须注明作者和版本。
例如：
/**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);
* win.show();
*
*
* @author Sami Shaio
* @version %I%, %G%
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}
2.3 构造函数注释
构造函数注释采用 /** … */，描述部分注明构造函数的作用，不一定有块标记部分。
例如：
/**
* 默认构造函数
*/
有例如：
/**
* 带参数构造函数,初始化模式名,名称和数据源类型
*
* @param schema
* Ref 模式名
* @param name
* Ref 名称
* @param type
* byVal 数据源类型
*/
2.4 域注释
域注释可以出现在注释文档里面，也可以不出现在注释文档里面。用/** … */的域注释将会被认为是注释文档热出现在最终生成的HTML报告里面，而使用/* … */的注释会被忽略。
例如：
/* 由于triger和表用一个DMSource，所以要区分和表的迁移成功标记 */
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 package.Class
@see package.Class#field
@see package.Class#Constructor(Type, Type...)
@see package.Class#Constructor(Type id, Type id)
@see package.Class#method(Type, Type,...)
@see package.Class#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可以省略，表示是值传递。
3.2.2 @return
标记
返回为空（void）的构造函数或者函数，@return可以省略。
如果返回值就是输入参数，必须用与输入参数的@param相同的描述信息。
必要的时候注明特殊条件写的返回值。
3.2.3 @throws
标记
@throws以前使用的是@exception。
@throws的内容必须在函数的throws部分定义。
3.2.4 @author
标记
类注释标记。
函数注释里面可以不出现@author。
3.2.5 @version
类注释标记。
函数注释里面可以不出现@version
3.2.6 @since
类注释标记。
标明该类可以运行的JDK版本
例如：
@since JDK1.2
3.2.7 @deprecated
由于某种原因而被宣布将要被废弃的方法。
/**
* @deprecated As of JDK 1.1, replaced by
* setBounds
* @see #setBounds(int,int,int,int)
*/
3.2.8 @link
标记
语法：{@link package.class#member label}
Label为链接文字。
package.class#member将被自动转换成指向package.class的member文件的URL。
4 HTML代码的使用
在注释描述部分可以使用HTML代码。
表示段落

表示自动标号

5 注释示例
/**
* Graphics is the abstract base class for all graphics contexts
* which allow an application to draw onto components realized on
* various devices or onto off-screen images.
* A Graphics object encapsulates the state information needed
* for the various rendering operations that Java supports. This
* state information includes:
*
*

*

*

*

*

*

*

* (see setXORMode)
*
*
* Coordinates are infinitely thin and lie between the pixels of the
* output device.
* Operations which draw the outline of a figure operate by traversing
* along the infinitely thin path with a pixel-sized pen that hangs
* down and to the right of the anchor point on the path.
* Operations which fill a figure operate by filling the interior
* of the infinitely thin path.
* Operations which render horizontal text render the ascending
* portion of the characters entirely above the baseline coordinate.
*
* Some important points to consider are that drawing a figure that
* covers a given rectangle will occupy one extra row of pixels on
* the right and bottom edges compared to filling a figure that is
* bounded by that same rectangle.
* Also, drawing a horizontal line along the same y coordinate as
* the baseline of a line of text will draw the line entirely below
* the text except for any descenders.
* Both of these properties are due to the pen hanging down and to
* the right from the path that it traverses.
*
* All coordinates which appear as arguments to the methods of this
* Graphics object are considered relative to the translation origin
* of this Graphics object prior to the invocation of the method.
* All rendering operations modify only pixels which lie within the
* area bounded by both the current clip of the graphics context
* and the extents of the Component used to create the Graphics object.
*
* @author Sami Shaio
* @author Arthur van Hoff
* @version %I%, %G%
* @since 1.0
*/
public abstract class Graphics {

/**
* Draws as much of the specified image as is currently available
* with its northwest corner at the specified coordinate (x, y).
* This method will return immediately in all cases, even if the
* entire image has not yet been scaled, dithered and converted
* for the current output device.
*
* If the current output representation is not yet complete then
* the method will return false and the indicated
* {@link ImageObserver} object will be notified as the
* conversion process progresses.
*
* @param img the image to be drawn
* @param x the x-coordinate of the northwest corner
* of the destination rectangle in pixels
* @param y the y-coordinate of the northwest corner
* of the destination rectangle in pixels
* @param observer the image observer to be notified as more
* of the image is converted. May be
* null
* @return true if the image is completely
* loaded and was painted successfully;
* false otherwise.
* @see Image
* @see ImageObserver
* @since 1.0
*/
public abstract boolean drawImage(Image img, int x, int y,
ImageObserver observer);
 
/**
* Dispose of the system resources used by this graphics context.
* The Graphics context cannot be used after being disposed of.
* While the finalization process of the garbage collector will
* also dispose of the same system resources, due to the number
* of Graphics objects that can be created in short time frames
* it is preferable to manually free the associated resources
* using this method rather than to rely on a finalization
* process which may not happen for a long period of time.
*
* Graphics objects which are provided as arguments to the paint
* and update methods of Components are automatically disposed
* by the system when those methods return. Programmers should,
* for efficiency, call the dispose method when finished using
* a Graphics object only if it was created directly from a
* Component or another Graphics object.
*
* @see #create(int, int, int, int)
* @see #finalize()
* @see Component#getGraphics()
* @see Component#paint(Graphics)
* @see Component#update(Graphics)
* @since 1.0
*/
public abstract void dispose();

/**
* Disposes of this graphics context once it is no longer
* referenced.
*
* @see #dispose()
* @since 1.0
*/
public void finalize() {
dispose();
}
}
The Component to draw on
A translation origin for rendering and clipping coordinates
The current clip
The current color
The current font
The current logical pixel operation function (XOR or Paint)
The current XOR alternation color

 

    public static void main(String[] args) {
//        BorrowerCollection bc = new BorrowerCollection("Test.txt");
        BorrowerCollection bc = new BorrowerCollection();
        System.out.println(bc.readFromFile("Test.txt").get(0).toString());
//        BorrowerCollection bc = new BorrowerCollection();
//        Borrower b = new Borrower(1, "Jack", "Tang", "Albertslund");
//        Borrower b1 = new Borrower(2, "Xiao", "Long", "København");
//        bc.addBorrower(b);
//        bc.addBorrower(b1);
//        bc.wirteToTextFile("Test3kkk.txt");

    }