JAVADOC注释详解 |
您所在的位置:网站首页 › 齿轮加叹号什么故障 › JAVADOC注释详解 |
java注释的分类
1、单行注释:int SUM = 100; //这是一个单行注释 2、多行注释: /* *这是一个多行注释 */ 3、文档注释: /** *这是一个文档注释 * @return a */
java注释和文档注释 作为一个java程序员我们一定都喜欢看官方的开发文档,文档中很详细的包括了类和接口参数方法等信息,并提供了许多类之间的关系等等。java的开发文档是由HTML页面进行展示的,但是用了很久我们才知道,这些文档实际上不是一点一点的写出来的,我们自己也可以进行生成。 安装了 JDK 之后,安装目录下有一个 src.jar 文件或者 src.zip 文件,它们都是以 ZIP 格式压缩的,可以使用 WinZip 解压。解压之后,我们就可以看到分目录放的全是 .java 文件。是了,这些就是 Java 运行类的源码了,非常完整,连注释都写得一清二楚,我们可以对比这里的注释和开发文档,以java.util.List为例:这是官网API截图 接下来再看一下源码信息: package java.util; /** * An ordered collection (also known as a sequence). The user of this * interface has precise control over where in the list each element is * inserted. The user can access elements by their integer index (position in * the list), and search for elements in the list. * * Unlike sets, lists typically allow duplicate elements. More formally, * lists typically allow pairs of elements e1 and e2 * such that e1.equals(e2), and they typically allow multiple * null elements if they allow null elements at all. It is not inconceivable * that someone might wish to implement a list that prohibits duplicates, by * throwing runtime exceptions when the user attempts to insert them, but we * expect this usage to be rare. * * The List interface places additional stipulations, beyond those * specified in the Collection interface, on the contracts of the * iterator, add, remove, equals, and * hashCode methods. Declarations for other inherited methods are * also included here for convenience. ..... * @param the type of elements in this list * * @author Josh Bloch * @author Neal Gafter * @see Collection * @see Set * @see ArrayList * @see LinkedList * @see Vector * @see Arrays#asList(Object[]) * @see Collections#nCopies(int, Object) * @see Collections#EMPTY_LIST * @see AbstractList * @see AbstractSequentialList * @since 1.2 */ public interface List extends Collection { ..... } 可以看出来,java的开发文档其实就是在将代码中的注释按照相应的规则整理出来的,这对程序的阅读者和使用者十分关键,由此可见,学会写注释对于一个程序员来说是十分关键的,也能体现一个程序员的水平。 文档和文档注释的格式文档注释可以用在类,方法,属性上进行说明。文档内部要注意细节问题。 文档的生成格式是HTML,而HTML中的格式标识符并不是javadoc加的,而是我们在写注释的时候写上去的,比如,需要换行的时候,不是敲入一个换行符,而是写一个,如果要分段,需要使用
因此,格式化文档,就是在注释中添加HTML相应的标签。
文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件),而是读取每一行后,删掉前导的 * 号及 * 号以前的空格,再输入到文档的。如: /** * This is first line. <br> * This is second line. <br> This is third line. */ 编译输出后的HTML源码则是: This is first line. <br> This is second line. <br> This is third line.
*注意,文档说明后面需要紧跟类、接口、方法或属性 文档注释的三个组成部分
第一个部分作为类、接口、方法、属性的简述。简述在文档注释的最前面,简述的末尾需要加上一个点号“.”,就是使用点号来分割文档注释,有的时候点号会出现错误,我们就用 作为第二部分的开头进行分割。 第二部分就是注释的详细部分,对属性或方法等进行详细的说明,在格式上没有什么特殊的要求。 第三部分是特殊说明部分,这个部分包括声明作者、版本说明、参数说明、参考说明、返回值说明。抛出异常说明等,这一部分最好和第二部分有一个空行,不然可能会出现错误。 1、@see的使用: @see的句法有三种 ①、@see 类名 类名可以根据需要只写出类名,如String,或者写出全名:java.lang.String,但需要注意的是,在用类名的时候需要这个java源文件中import这个类,否则只能用全名。 ②、@see#方法名或属性名 如果是属性名,则只需要写出属性名即可,如果是方法名,则需要写出方法名以及参数类型,如果没有参数,也需要写出一对括号。 如:@see #contains(Object)、@see #count()、@see number ③、@see 类名#方法名或属性名 如:@see Object#equals(Object)、@see java.lang.String#toString() 2、@author、@version的使用: 这两个标记分别指明作者和版本号,缺省情况下javadoc自动将其忽略,但命令行开关-author和-version可以修改个功能,使其包含的信息流输出,这两个标记都可以多个使用,但是版本号只有第一个出现的有效。 3、@param、@return和@exception的使用: 这三个标记只能用于方法,@param描述参数,@return描述返回值,@exception描述抛出异常,用法如下: ①、@param 参数名 参数说明 每一个@param都只能描述一个方法的参数,可以多次使用。 ②、@return 返回值说明 一个方法只能使用一个@return,如果有多个,javadoc会发出警告,并且只有第一个声明的有效。 @exception 异常类名 异常说明 @exception可以多次使用,并且异常的类名需要注意在java原文件中是否有导入,如果没有需要写类全名。 如: /** * test 方法的简述,这个方法用于做javadoc的测试. * test方法的详细说明,这里是详细说明的第一行 * test方法详细说明的第二行 * * @param a firstnum * @param b lastnum * @exception java.lang.ArithmeticException throw when b is 0 * @return 返回值为a/b */ public int test(int a,int b) throws java.lang.ArithmeticException{ return a/b; } *注意:写文档注释的时候应该注意正确的匹配参数,javadoc在一定程度上不会检查我们写的文档注释,如果写错误可能会造成一些困惑 javadoc命令用法:javadoc [options] [packagenames] [sourcefiles] 选项: -public 仅显示 public 类和成员 -protected 显示 protected/public 类和成员 (缺省) -package 显示 package/protected/public 类和成员 -private 显示所有类和成员 -d <directory> 输出文件的目标目录 -version 包含 @version 段 -author 包含 @author 段 -splitindex 将索引分为每个字母对应一 个文件 -windowtitle <text> 文档的浏览器窗口标题 javadoc可以给定包列表进行编译,如:javadoc xcg xcg.test 也可以给出源文件列表,如:javadoc xcg/test/JavaDocTest.java 以上两种方式的编译结果不同,用包列表生成的文档被框架分成了三个部分:包列表、类列表和类说明 在eclipse或myeclipse中可以使用file->Export->javadoc可以进行手动输出javadoc,需要注意生成的时候可能会出现错误: 编码GBK的不可映射字符,这时就需要在流程的最后一步加上一句话控制字符:-encoding UTF-8 -charset UTF-8,如: 1、注释原则: ①注释形式统一 ②注释内容准确简单 2、注释条件: ①基本注释(必须加):类、接口的注释、构造函数的注释、方法的注释、全局变量的注释、字段/属性的注释 ②特殊必须加的注释:典型算法、代码不清晰易懂时加注释、修改代码时需要加注释、在循环分支需要加注释、为他人提供的接口等信息必须加注释。
|
今日新闻 |
点击排行 |
|
推荐新闻 |
图片新闻 |
|
专题文章 |
CopyRight 2018-2019 实验室设备网 版权所有 win10的实时保护怎么永久关闭 |