JAVADOC注释详解

JAVADOC注释详解java注释的分类   1、单行注释:intSUM=100; //这是一个单行注释   2、多行注释:    /*    *这是一个多行注释    */   3、文档注释:    /**    *这是一个文档注释    *@returna    */java注释和文档注释   作为一个jav

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截图

JAVADOC注释详解

    接下来再看一下源码信息:

package java.util;

/**
 * An ordered collection (also known as a <i>sequence</i>).  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.<p>
 *
 * Unlike sets, lists typically allow duplicate elements.  More formally,
 * lists typically allow pairs of elements <tt>e1</tt> and <tt>e2</tt>
 * such that <tt>e1.equals(e2)</tt>, 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.<p>
 *
 * The <tt>List</tt> interface places additional stipulations, beyond those
 * specified in the <tt>Collection</tt> interface, on the contracts of the
 * <tt>iterator</tt>, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt>, and
 * <tt>hashCode</tt> methods.  Declarations for other inherited methods are
 * also included here for convenience.<p>

…..

 * @param <E> 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<E> extends Collection<E> {

…..

}

    可以看出来,java的开发文档其实就是在将代码中的注释按照相应的规则整理出来的,这对程序的阅读者和使用者十分关键,由此可见,学会写注释对于一个程序员来说是十分关键的,也能体现一个程序员的水平。

文档和文档注释的格式

    文档注释可以用在类,方法,属性上进行说明。文档内部要注意细节问题。

    文档的生成格式是HTML,而HTML中的格式标识符并不是javadoc加的,而是我们在写注释的时候写上去的,比如,需要换行的时候,不是敲入一个换行符,而是写一个<br>,如果要分段,需要使用<p>

   

    因此,格式化文档,就是在注释中添加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.

    *注意,文档说明后面需要紧跟类、接口、方法或属性

文档注释的三个组成部分 

JAVADOC注释详解   JAVADOC注释详解

    第一个部分作为类、接口、方法、属性的简述。简述在文档注释的最前面,简述的末尾需要加上一个点号“.”,就是使用点号来分割文档注释,有的时候点号会出现错误,我们就用<p>作为第二部分的开头进行分割。

    第二部分就是注释的详细部分,对属性或方法等进行详细的说明,在格式上没有什么特殊的要求。

    第三部分是特殊说明部分,这个部分包括声明作者、版本说明、参数说明、参考说明、返回值说明。抛出异常说明等,这一部分最好和第二部分有一个空行,不然可能会出现错误。 JAVADOC注释详解

JAVADOC注释详解

常用的javadoc标记及其使用

JAVADOC注释详解

    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的测试.
     * <p> test方法的详细说明,这里是详细说明的第一行<br>
     * 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,如:

JAVADOC注释详解JAVADOC注释详解

注释规范

    1、注释原则:

      ①注释形式统一

      ②注释内容准确简单

    2、注释条件:

      ①基本注释(必须加):类、接口的注释、构造函数的注释、方法的注释、全局变量的注释、字段/属性的注释

      ②特殊必须加的注释:典型算法、代码不清晰易懂时加注释、修改代码时需要加注释、在循环分支需要加注释、为他人提供的接口等信息必须加注释。

今天的文章JAVADOC注释详解分享到此就结束了,感谢您的阅读。

版权声明:本文内容由互联网用户自发贡献,该文观点仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 举报,一经查实,本站将立刻删除。
如需转载请保留出处:https://bianchenghao.cn/6829.html

(0)
编程小号编程小号

相关推荐

发表回复

您的电子邮箱地址不会被公开。 必填项已用*标注