Java中javadoc注释使用规则

分享到:
           

    在Java中,提供了3种注释方式:短(单行)注释、块(多行)注释及文档注释。单行和多行注释很容易理解,将注释符之间的内容当做注释,在编译和运行时将这部分内容忽略。下面介绍单行注释和多行注释的方法。

    (1)单行注释:单行注释就是在程序中注释一行代码。

    注释规则:在代码中单起一行注释, 注释前好有一行空行,并与其后的代码具有一样的缩进层级。如果单行无法完成,则应采用块注释。

    注释格式::

    // 注释内容

    (2)多行注释:一次将程序中的多行注释掉。

    注释规则:注释若干行,通常用于提供文件、方法、数据结构等的意义与用途的说明,或者算法的描述。一般位于一个文件或者一个方法的前面,起到引导的作用,也可以根据需要放在合适的位置。

    注释格式:

    /*
    注释内容
    */

    来看一个单行注释和多行注释的例子。

    源文件:MessageComment.java

    //这是一个单行注释
    /*
    这是一个
    多行注释
    */
    public class MessageComment {
        public static void main(String[] args) {
            System.out.println("发信息");
            // System.out.println("此条信息不会显示");
        }
    }

    在Java中,比较特殊的是javadoc注释,包含在这部分中的注释可以通过javadoc命令来自动生成API文档。通过javadoc工具,可以保证程序代码和技术文档的同步。在修改了程序中的注释后,只需要通过javadoc,就可以方便地生成相应的技术文档。

    我们知道,在软件开发过程中,文档编写的重要性不亚于程序代码本身。如果代码与文档是分离的,那么在每次修改代码时,都需要修改相应的文档就会是一件很麻烦的事情。 所以通过javadoc将代码同文档“连接”起来。在Java中,还有一种特别的注释方式:文档注释。利用这种注释,可以从Java源文件中提取这些注释的内容,来产生HTML格式的API文档。

    文档注释的基本格式如下:

    /**
    文档注释内容
    */

    注意把文档注释和多行注释区分清楚,文档注释的开始标记是“/**”,而多行注释标记的开始标记是“/*”。

    由于文档注释重要的一个功能就是用它来生成HTML格式的API文档,因此,很多用于HTML格式化的HTML标记也可以用在文档注释中,在从这些注释中提取注释生成HTML文件的时候,在生成的HTML文件中,将使用这些HTML标记来格式化HTML文件内容。常用的HTML标记有<b>…</b>、<code>…</code>等。关于这些HTML标记及其他的HTML标记,请读者参考相关的HTML资料。

    和多行注释不同的另一个地方是,文档注释并不是可以放在Java代码的任何地方,javadoc工具在从Java代码中提取注释生成API文档时,主要从以下几项内容中提取信息。

    ·包。
    ·公有(public)类与接口。
    ·公有方法和受保护(protected)方法。
    ·公有属性和受保护属性。

    因此,文档注释也应该放到相应的位置中。

    1.文档注释位置

    (1)类注释。类注释用于说明整个类的功能、特性等,它应该放在所有的“import”语句之后,在class定义之前。

    这个规则也适用于接口(interface)注释。

    (2)方法注释。方法注释用来说明方法的定义,比如,方法的参数、返回值及说明方法的作用等。方法注释应该放在它所描述的方法定义前面。

    (3)属性注释。默认情况下,javadoc只对公有(public)属性和受保护属性(protected)产生文档——通常是静态常量。

    (4)包注释。类、方法、属性的注释都直接放到Java的源文件中,而对于包的注释,无法放到Java文件中去,只能通过在包对应的目录中添加一个package.html的文件来达到这个目的。当生成HTML文件时,package.html文件的<BODY>和</BODY>部分的内容将会被提取出来当做包的说明。关于包注释,后面还会有更进一步的解释。

    (5)概要注释。除了包注释外,还有一种类型的文档无法从Java源文件中提取,就是对所有类文件提供概要说明的文件。同样的,也可以为这类注释单独新建一个HTML文件,这个文件的名字为“overview.html”,它的<BODY>和</BODY>标记之间的内容都会被提取。

    2.javadoc标记

    在javadoc注释中,常用@来表示一个javadoc标记,常用的javadoc标记如下:

    ·@author:作者。
    ·@version:版本。
    ·@docroot:表示产生文档的根路径。
    ·@deprecated:不推荐使用的方法。
    ·@param:方法的参数类型。
    ·@return:方法的返回类型。
    ·@see:用于指定参考的内容。
    ·@exception:抛出的异常。
    ·@throws:抛出的异常,和exception同义。

    需要注意这些标记的使用是有位置限制的。其中可以出现在类或者接口文档注释中的标记有:@see、@deprecated、@author、@version等。可以出现在方法或者构造器文档注释中的标记有:@see、@deprecated、@param、@return、@throws、@exception等。可以出现在属性文档注释中的有:@see、@deprecated等。

    3.javadoc命令语法

    javadoc的命令行语法如下:

    javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]

    参数可以按照任意顺序排列。下面对这些参数作一些说明。

    (1)packagenames 包列表:这个选项可以是一系列的包名(用空格隔开),例如,java.lang java.lang.reflect java.awt。因为javadoc不递归作用于子包,不允许对包名使用通配符;所以必须显式地列出希望建立文档的每一个包。

    (2)sourcefiles 源文件列表。这个选项可以是一系列的源文件名(用空格隔开),可以使用通配符。javadoc允许4种源文件:类源代码文件、包描述文件、总体概述文件、其他杂文件。

    ·类源代码文件:类或者接口的源代码文件。

    ·包描述文件:每一个包都可以有自己的包描述文件。包描述文件的名称必须是 “package.html”,与包的.java文件放置在一起。包描述文件的内容通常是使用HTML标记写的文档。javadoc执行时将自动寻找包描述文件。如果找到,javadoc将首先对描述文件中<body></body>之间的内容进行处理,然后把处理结果放到该包的Package Summary页面中,后把包描述文件的第一句(紧靠<body>)放到输出的Overview Summary页面中,并在语句前面加上该包的包名。

    总体概述文件:javadoc可以创建一个总体概述文件描述整个应用或者所有包。总体概述文件可以被任意命名,也可以放置到任意位置。-overview选项可以指示总体概述文件的路径和名称。总体概述文件的内容是使用HTML标记写的文档。javadoc在执行的时候,如果发现-overview选项,那么它将首先对文件中<body></body>之间的内容进行处理;然后把处理后的结果放到输出的Overview Summary 页面的底部;后把总体概述文件中的第一句放到输出的Overview Summary页面的顶部。

    其他杂文件:这些文件通常是指与javadoc输出的HTML文件相关的一些图片文件、Java源代码文件(.java)、Java程序(.class)、Java小程序(Applets)、HTML文件。这些文件必须放在doc-files目录中。每一个包都可以有自己的doc-files目录。例如,你希望在java.awt.Button的HTML文档中使用一幅按钮的图片(Button.gif)。首先,必须把图片文件放到java\awt\doc-files\中;然后在Button.java文件中加入以下注释:

    /**
    * This button looks like this:
    * <img src="doc-files/Button.gif">
    */

    files 包含文件。为了简化javadoc命令,可以把需要建立文档的文件名和包名放在一个或多个文本文件中。例如,为了简化以下命令:

    javadoc -d apidoc com.oristand.college com.oristand.school

    可以建立一个名称为mypackage.txt的文件,其内容如下:

    com.oristand.college
    com.oristand.school

    然后执行以下命令即可:

    javadoc -d apidoc @mypackage.txt

    ·options 命令行选项。

    ① public 只显示公共类及成员。
    ② protected 只显示受保护的和公共的类及成员。默认选项。
    ③ package只显示包、受保护的和公共的类及成员。
    ④ private 显示所有类和成员。

    -classpath classpathlist 指定javadoc查找“引用类”的路径。引用类是指带文档的类加上它们引用的任何类。javadoc将搜索指定路径的所有子目录,classpathlist可以包含多个路径(使用“;”隔开)。

    一切就绪后,就可以使用JDK中的“javadoc”工具来生成相关的API文档了。

   热点链接:

   1、Java源文件结构详解
   2、Java中的类和对象
   3、Java构造器的使用方法
   4、Java驱动在智能嵌入式设备上更具优势
   5、嵌入式linux内核数据结构之循环链表

更多新闻>>