java文档注释
2015-04-22 15:32
134 查看
Java有三种注释方式。前两种分别是
说明注释允许你在程序中嵌入关于程序的信息。你可以使用javadoc工具软件来生成信息,并输出到HTML文件中。说明注释使你更加方便地记录你的程序信息。
注释文档将用来生成HTML格式的代码报告,所以注释文档必须书写在类、域、构造函数、方法、定义之前。注释文档由两部分组成——描述、块标记。
下面是一个类的说明注释的示例:
第一行为描述,描述完毕后,由@符号起头为块标记注释。
每一个类的信息将在独自的HTML文件里。javadoc也可以输出继承的树形结构和索引。
由于javadoc的实现不同,工作也可能不同,你需要检查你的Java开发系统的版本等细节,选择合适的Javadoc版本。
实例:
下面是一个使用说明注释的简单实例。注意每一个注释都在它描述的项目的前面。
在经过javadoc处理之后,SquareNum类的注释将在SquareNum.html中找到。
使用javadoc工具处理SquareNum.java文件:$ javadoc SquareNum.java
例如:
例如:
例如:
例如:
一个块标记可以根据需要重复出现多次,多次出现的标记按照如下顺序:
@param后面空格后跟着参数的变量名字(不是类型),空格后跟着对该参数的描述。
在描述中第一个名字为该变量的数据类型,表示数据类型的名字前面可以有一个冠词如:a,an,the。如果是int类型的参数则不需要注明数据类型。例如:
对于参数的描述如果只是一短语,最好不要首字母大写,结尾也不要句号。
对于参数的描述是一个句子,最好不要首字母大写,如果出现了句号这说明你的描述不止一句话。如果非要首字母大写的话,必须用句号来结束句子。(英文的句号)
公司内部添加ByRef和ByVal两个标记,例如:
说明该参数是引用传递(指针),ByVal可以省略,表示是值传递。
2.2 @return标记
返回为空(void)的构造函数或者函数,@return可以省略。
如果返回值就是输入参数,必须用与输入参数的@param相同的描述信息。
必要的时候注明特殊条件写的返回值。
2.3 @throws标记
@throws以前使用的是@exception。
@throws的内容必须在函数的throws部分定义。
2.4 @author标记
类注释标记。
函数注释里面可以不出现@author。
2.5 @version标记
类注释标记。
函数注释里面可以不出现@version
2.6 @since标记
类注释标记。
标明该类可以运行的JDK版本
例如:
@since JDK1.2
2.7 @deprecated标记
由于某种原因而被宣布将要被废弃的方法。
2.8 @link标记
语法:{@link package.class#member label}
Label为链接文字。
package.class#member将被自动转换成指向package.class的member文件的URL。
参考:
http://blog.csdn.net/afeilxc/article/details/4060089#t1
http://c.biancheng.net/cpp/html/1761.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 info |
注释文档的格式
在开始的/**之后,第一行或几行是关于类、变量和方法的主要描述。之后,你可以包含一个或多个各种各样的@标签。每一个@标签必须在一个新行的开始或者在一行的开始紧跟星号(*)。多个相同类型的标签应该放成一组。例如,如果你有三个@see标签,可以将它们一个接一个的放在一起。
注释文档将用来生成HTML格式的代码报告,所以注释文档必须书写在类、域、构造函数、方法、定义之前。注释文档由两部分组成——描述、块标记。
下面是一个类的说明注释的示例:
/** * This class draws a bar chart. * @author Zara Ali * @version 1.2 */
第一行为描述,描述完毕后,由@符号起头为块标记注释。
javadoc输出什么
javadoc工具将你的Java程序的源代码作为输入,输出一些包含你程序注释的HTML文件。每一个类的信息将在独自的HTML文件里。javadoc也可以输出继承的树形结构和索引。
由于javadoc的实现不同,工作也可能不同,你需要检查你的Java开发系统的版本等细节,选择合适的Javadoc版本。
实例:
下面是一个使用说明注释的简单实例。注意每一个注释都在它描述的项目的前面。
在经过javadoc处理之后,SquareNum类的注释将在SquareNum.html中找到。
import java.io.*; /** * This class demonstrates documentation comments. * @author Ayan Amhed * @version 1.2 */ public class SquareNum { /** * This method returns the square of num. * This is a multiline description. You can use * as many lines as you like. * @param num The value to be squared. * @return num squared. */ public double square(double num) { return num * num; } /** * This method inputs a number from the user. * @return The value input as a double. * @exception IOException On input error. * @see IOException */ public double getNumber() throws IOException { InputStreamReader isr = new InputStreamReader(System.in); BufferedReader inData = new BufferedReader(isr); String str; str = inData.readLine(); return (new Double(str)).doubleValue(); } /** * This method demonstrates square(). * @param args Unused. * @return Nothing. * @exception IOException On input error. * @see IOException */ public static void main(String args[]) throws IOException { SquareNum ob = new SquareNum(); double val; System.out.println("Enter value to be squared: "); val = ob.getNumber(); val = ob.square(val); System.out.println("Squared value is " + val); } }
使用javadoc工具处理SquareNum.java文件:$ javadoc SquareNum.java
注释的种类
1.文件头注释
文件头注释以/*开始,以
*/结束,需要注明该文件创建时间,文件名,命名空间信息。
例如:
/* * Created on 2005-7-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 { ... }
3.构造函数注释
构造函数注释采用/** … */,描述部分注明构造函数的作用,不一定有块标记部分。
例如:
/** * 默认构造函数 */
/** * 带参数构造函数,初始化模式名,名称和数据源类型 * * @param schema * Ref 模式名 * @param name * Ref 名称 * @param type * byVal 数据源类型 */
4.域注释
域注释可以出现在注释文档里面,也可以不出现在注释文档里面。用/** … */的域注释将会被认为是注释文档而出现在最终生成的HTML报告里面,而使用
/* … */的注释会被忽略。
例如:
/* 由于triger和表用一个DMSource,所以要区分和表的迁移成功标记 */ boolean isTrigerSuccess = false;
/** 由于triger和表用一个DMSource,所以要区分和表的迁移成功标记 */ boolean isTrigerSuccess = false;
/** * The X-coordinate of the component. * * @see #getLocation() */ int x = 1263732;
5.方法注释
方法注释采用/** … */,描述部分注明方法的功能,块标记部分注明方法的参数,返回值,异常等信息。例如:
/** * 设置是否有外码约束 * * @param conn * Connection 与数据库的连接 */
6.定义注释
规则同域注释。注释块标记
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
2.标记介绍
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可以省略,表示是值传递。
2.2 @return标记
返回为空(void)的构造函数或者函数,@return可以省略。
如果返回值就是输入参数,必须用与输入参数的@param相同的描述信息。
必要的时候注明特殊条件写的返回值。
2.3 @throws标记
@throws以前使用的是@exception。
@throws的内容必须在函数的throws部分定义。
2.4 @author标记
类注释标记。
函数注释里面可以不出现@author。
2.5 @version标记
类注释标记。
函数注释里面可以不出现@version
2.6 @since标记
类注释标记。
标明该类可以运行的JDK版本
例如:
@since JDK1.2
2.7 @deprecated标记
由于某种原因而被宣布将要被废弃的方法。
/** * @deprecated As of JDK 1.1, replaced by setBounds * @see #setBounds(int,int,int,int) */
2.8 @link标记
语法:{@link package.class#member label}
Label为链接文字。
package.class#member将被自动转换成指向package.class的member文件的URL。
参考:
http://blog.csdn.net/afeilxc/article/details/4060089#t1
http://c.biancheng.net/cpp/html/1761.html
相关文章推荐
- Java文档注释说明
- 了解JAVA,注释,API文档,关键字和标识符,进制转换
- 黑马程序员_Java基础 数组、数组工具类、文档注释总结
- 从Java源文件中批量榨取注释到设计文档
- java文档注释
- 5.14 Java文档注释(?)
- Java-文档注释
- java文档注释(有示例)
- Java 文档注释
- Java 从基础到进阶学习之路---类编写以及文档注释.
- 用javadoc提取此注释文档,并产生一个HTML文件,最后通过浏览器查看结果 直接Tools>Generate javadoc
- MyEclipse设置java类文档注释
- Java中文档注释的模板修改及添加注释的快捷键
- Java 文档注释
- JAVA文档注释与多行注释的区别
- 如何将java程序中的文档注释提取出来生成说明文档
- Eclipse中java生成注释文档
- java文档注释
- 虽然微不足道但是很有用的JAVA基础—注释与文档标记
- java学习笔记(四)----对象、数组作为参数传递,静态变量、静态方法的使用,内部类,使用文档注释