Java支持三种形式的注释。前两种是// 和/* */。第三种方式被称为文档注释。它以“/**”开始,以“*”标志结束。文档注释提供将程序信息嵌入程序的功能。开发者可以使用javadoc工具将信息取出,然后转换为HTML文件。文档注释提供了编写程序文档的便利方式。javadoc工具生成的文档几乎人人都看过,因为Sun的Java API文档库就是这么生成的。
javadoc标记
javadoc实用程序识别下列标记:
Tag标记
|
意义
|
@author
|
确定类的作者
|
@deprecated
|
指示反对使用这个类或成员
|
{@docRoot}
|
指定当前文档的根目录路径 (Java 2的1.3版新增)
|
@exception
|
确定一个方法引发的异常
|
{@link}
|
插入对另一个主题的内部链接
|
@param
|
为方法的参数提供文档
|
@return
|
为方法的返回值提供文档
|
@see
|
指定对另一个主题的链接
|
@serial
|
为默认的可序列化字段提供文档
|
@serialData
|
为writeObject()或者writeExternal()方法编写的数据提供文档
|
@serialField
|
为ObjectStreamField组件提供文档
|
@since
|
当引入一个特定改变时,声明发布版本
|
@throws
|
与@exception相同
|
@version
|
指定类的版本
|
正如上面看到的那样,所有的文档标记都以“(@)”标志开始。在一个文档注释中,也可以使用其他的标准HTML标记。然而,一些标记(如标题)是不能使用的,因为它们会破坏由javadoc生成的HTML文件外观。
可以使用文档注释为类、接口、域、构造函数和方法提供文档。在所有这些情况中,文档注释必须紧接在被注释的项目之前。为变量做注释,可以使用@see, @since, @serial, @serialField, 和@deprecated文档标记。为类做注释,可以使用@see, @author, @since, @deprecated, 和@version文档标记。方法可以用@see, @return, @param, @since, @deprecated, @throws, @serialData, 和@exception做标记。而{@link}
或 {@docRoot}标记可以用在任何地方。下面详细列出了每个标记的使用方法:
@ author
标记@author 指定一个类的作者,它的语法如下:
@author description
其中, description 通常是编写这个类的作者名字。标记@author 只能用在类的文档中。在执行javadoc时,你需要指定-author 选项,才可将@author 域包括在HTML文档中。
@deprecated
@deprecated 标记指示不赞成使用一个类或是一个成员。建议使用@see 标记指示程序员其他可用的选择。其语法如下:
@deprecated description
其中description 是描述反对的信息。由@deprecated 标记指定的信息由编译器识别,包括在生成的.class文件中,因此在编译Java源文件时,程序员可以得到这个信息。@deprecated 标记可以用于变量,方法和类的文档中。
{@docRoot}
{@docRoot}指定当前文档的根目录路径。
@exception
@exception 标记描述一个方法的异常,其语法如下:
@exception exception-name explanation
其中,异常的完整名称由exception-name指定,explanation 是描述异常如何产生的字符串。@exception 只用于方法的文档。
{@link}
{@link} 标记提供一个附加信息的联机超链接。其语法如下:
{@link name text}
其中,name 是加入超链接的类或方法的名字, text 是显示的字符串。
@param
@param 标记注释一个方法的参数。其语法如下所示:
@param parameter-name explanation
其中parameter-name指定方法的参数名。这个参数的含义由explanation描述。@param 标记只用在方法的文档中。
@return
@return 标记描述一个方法的返回值。其语法如下:
@@return explanation
其中,explanation 描述方法返回值的类型和含意。@return 标记只用在方法的文档中。
@see
@see 标记提供附加信息的引用。最常见的使用形式如下所示:
@see anchor
@see pkg.class#member text
在第一种格式中,ancho 是一个指向绝对或相对URL的超链接。第二种格式, pkg.class#member 指示项目的名字,text是项目的文本显示。文本参数是可选的,如果不用,显示由pkg.class#membe 指定的项目。成员名,也是可选的。因此,除了指向特定方法或者字段的引用之外,你还可以指定一个引用指向一个包,一个类或是一个接口。名字可以是完全限定的,也可以是部分限定的。但是,成员名(如果存在的话)之前的点必须被替换成一个散列字符。
@serial
@serial 标记为默认的可序列化字段定义注释文档。其语法如下:
@serial description
其中, description 是字段的注释。
@serialData
@serialData 标记为writeObject()或者 writeExternal()方法编写的数据提供文档。其语法如下:
@serialData description
其中,description 是数据的注释。
@serialField
@serialField 标记为ObjectStreamField组件提供注释,其语法如下:
@serialField name type description
其中,name是域名,type是域的类型,description是域的注释。
@since
@since标记声明由一个特定发布版本引入的类或成员。其语法如下:
@since release
其中,release是指示这个特性可用的版本或发布的字符串。@since 标记可以用在变量、方法和类的文档中。
@throws
@throws 标记与@exception标记的含义相同。
@version
@version标记指示类的版本。其语法如下:
@version info
其中,info 是包含版本信息的字符串,典型情况下是如2.2这样的版本号。@version标记只用在类的文档中。在执行javadoc时,指定-version 选项,可将@version域包含在HTML文档中。
文档注释的一般形式
在用/**开头后,第一行,或者头几行是类、变量或方法的主要描述。其后,可以包括一个或多个不同的@标记。每个@标记必须在一个新行的开头,或者跟随一个星号(*)。同类型的多个标记应该组合在一起。例如,如果有三个@see标记,最好是一个挨着一个。
下面是一个类的文档注释的例子:
/**
* This class draws a bar chart.
* @author Herbert Schildt
* @version 3.2
*/
javadoc的输出
javadoc程序将Java程序的源文件作为输入,输出几个包含该程序文档的HTML文件。每个类的信息在其自己的HTML文件中。同时,javadoc还输出一个索引和一个层次结构树。Javadoc还可生成其他HTML文件。不同实现版本的javadoc可能工作方式有所不同,应该仔细阅读Java开发系统的说明书以了解此版本的细节处理。
一个使用文档注释的例子
下面是一个使用文档注释的程序范例。注意每个注释都在它描述的对象之前。在javadoc处理之后,SquareNum.html就是关于SquareNum类的文档。
import java.io.*;
/**
* This class demonstrates documentation comments.
* @author Herbert Schildt
* @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 {
// create a BufferedReader using System.in
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);
}
分享到:
相关推荐
这份文档详细说明了myEclipse/Eclipse中是如何配置java文档注释的,每次在myEclipse/Eclipse中写java代码时就可以用同一的文档注释了,减少了手工注释的麻烦。
一个好的程序员工资的体现不仅仅在于技术的强弱,还体现在注释的书写上
这个是java文档注释模板,使用myeclipse创建的,里面添加了基本颜色,只需导进到开发工具就可以了
java注释全解,内容全面,包括hibernate注解、Java注解、Spring注解、SSH全注解等内容,分为4个文档介绍。另附一些精品java学习资料,欢迎大家下载学习。
有关于java的注释规范的详细描述,单行注释、多行注释、分块注释等这些java的三种注释方式
eclipse中java类注释模板,有需要的朋友可以参考使用。
Java注释的良好习惯,方便项目的交接和事后的维护与整理,是一个很好的帮助自己养成编码习惯的工具,效果图在我的博文有记录,有需要的伙伴可以自行下载哦~
Java-文档注释例子
具体内容可参阅主页文章:【2023,学点儿新Java-09】Java初学者常会犯的错误总结与解决方案 | Java中的注释类型 | 详细教学:通过命令行 执行 Java中特有的文档注释
java编码规范及注释快捷键.doc
后端开发技术的代码注释规范 单行注释 多行注释 块注释 文档注释 标签注释等等
java程序注释的规范,每个初学者都应该掌握规范进行编程开发和学习,习惯了规范,自然就会提升代码的质量,提升团队的开发进度!
Eclipse Java 注释模板,设置后可以使用快捷键快速生成文档注释,版本信息等。
JAVA Eclipse注释和代码模板。使用时请注意,将文档打开,然后将第一行的空行删去,否则无法导入。
我们都阅读过 JDK API,但是庞大的API文档是怎么生成的?有谁知道 如何能保持代码的修改与代码文档的同步?这就是 javadoc 的存在目的。 这个文档将详细讲解 代码注释 怎么成为代码说明文档。
Java编程规范+文档注释+程序调试,前人总结的编程经验,经典啊!
本文档详细介绍了Java中的注释类型,包括单行注释、多行注释和文档注释。...查阅Java文档生成工具的使用方法,尝试为自己的项目生成API文档; 参与开源项目或团队合作,学习他人的注释风格和技巧。
赠送jar包:javacv-1.5.7.jar; 赠送原API文档:javacv-1.5.7-javadoc.jar; 赠送源代码:javacv-1.5.7-sources.jar;...人性化翻译,文档中的代码和结构保持不变,注释和说明精准翻译,请放心使用。
本文档是 Java 2 Platform Standard Edition 6.0 的 API 规范。 请参见: 描述 Java 2 Platform 软件包 java.applet 提供创建 applet 所必需的类和 applet 用来与其 applet 上下文通信的类。 java.awt 包含...