zoukankan      html  css  js  c++  java
  • Java学习笔记(十五)——javadoc学习笔记和可能的注意细节

    【前面的话】

          这次开发项目使用jenkins做持续集成,PMD检查代码,Junit做单元测试,还会自动发邮件通知编译情况,会将javadoc生成的文档自动发到一个专门的服务器上面,每个人都可以看,所以搞得我还必须好好学习一下JavaDoc,别人看到也可以美观一点。

    【基础知识】

    一、JavaDoc简介And基础知识

    (一) Java注释类型

    1. //用于单行注释。
    2. /*...*/用于多行注释,从/*开始,到*/结束,不能嵌套。
    3. /**...*/则是为支持jdk工具javadoc.exe而特有的注释语句。

         说明:javadoc 工具能从java源文件中读取第三种注释,并能识别注释中用@标识的一些特殊变量(见表),制作成Html格式的类说明文档。javadoc不但能对一个 java源文件生成注释文档,而且能对目录和包生成交叉链接的html格式的类说明文档,十分方便。

    (二)JavaDoc中出现的@字符及其意义:

         1. 通用注释

    注释中可以出现的关键字以@开始

    意义

    @author

    作者名

    @version

    版本标识

    @since

    最早出现的JDK版本

    @deprecated

    引起不推荐使用的警告  

    @see

    交叉参考

        2. 方法注释

    @return

    返回值

    @throws

    异常类及抛出条件

    @param

    参数名及其意义

    (三)举个例子:

          我们定义一个BusTestJavaDoc类用来具体说明运用javadoc 命令时对注释的规范。

         1. 汽车类有4个属性:

          1)maxSpeed——最大速度

          2)averageSpeed——平均速度

          3)waterTemperature——水温

          4)Temperature——室温

         2. 两个方法:

         1)measureAverageSpeed() ——汽车的平均速度

         2)measureMaxSpeed()——最大速度

        3.BusTestJavaDoc.java例子:

     1 /**
     2 *汽车类的简介
     3 *<p>汽车类具体阐述第一行<br>
     4 *汽车类具体阐述第二行
     5 *@author man
     6 *@author man2
     7 *@version 1.0
     8 *@see ship
     9 *@see aircraft
    10 */
    11 public class BusTestJavaDoc{
    12     /**
    13     *用来标识汽车行驶当中最大速度
    14     *@see #averageSpeed
    15     */
    16     public int maxSpeed;
    17     /**用来标识汽车行驶当中平均速度*/
    18     public int averageSpeed;
    19     /**用来标识汽车行驶当中的水温*/
    20     public int waterTemperature;
    21     /**用来标识天气温度*/
    22     public int Temperature;
    23     BusTestJavaDoc(){
    24         
    25     }
    26     /**
    27      *该方法用来测量一段时间内的平均速度
    28      *@param start 起始时间
    29      *@param end 截止时间
    30      *@return 返回int型变量
    31      *@exception java.lang.exceptionthrowwhenswitchis1
    32      */
    33     public int measureAverageSpeed(int start,int end ){
    34         int aspeed=12;
    35         return aspeed;
    36         }
    37     /**
    38      * 该方法用来测量最大速度
    39      */
    40     public int measureMaxSpeed(){
    41         return maxSpeed;
    42         
    43     }
    44 }

        4. eclipse中导出Html文档:

           export——java——javadoc——选择存储位置,可以看看生产的Javadoc

    二、javadoc的几种注释

    (一)类注释

         类注释出现在import语句之后,类定义之前,可以使用通用注释,如下:

     1 /**
     2 *汽车类的简介
     3 *<p>汽车类具体阐述第一行<br>
     4 *汽车类具体阐述第二行
     5 *@author man
     6 *@author man2
     7 *@version 1.0
     8 *@see ship
     9 *@see aircraft
    10 */
    11 public class BusTestJavaDoc{
    12 }

    (二)方法注释

          每一个方法注释必须放在所描述的方法之前,除了使用通用注释,还可以使用方法注释。如下:

     1 /**
     2      *该方法用来测量一段时间内的平均速度
     3      *@param start 起始时间
     4      *@param end 截止时间
     5      *@return 返回int型变量
     6      *@exception java.lang.exceptionthrowwhenswitchis1
     7      */
     8 public int measureAverageSpeed(int start,int end ){
     9         int aspeed=12;
    10         return aspeed;
    11         }

    (三)域注释

         只需对公有域进行注释,可以使用通用注释,如下:

    1 /**
    2     *用来标识汽车行驶当中最大速度
    3     *@see #averageSpeed
    4     */
    5     public int maxSpeed;

    (四)包注释与概述注释

          对于类,方法,变量的注释放置在Java源文件中就可以了,只需使用/**···*/文档注释界定就可以了,如果要对包进行注释,需要在每一个包目录中添加一个单独的文件。如下:

    1. 提供一个package.html命名的HTML文档。标记<BODY>···</BODY>之间的所有文本都会被抽取出来。
    2. 提供一个package-info.java命名的java文件。这个文件必须包含一个初始的以/**和*/界定的javadoc注释,跟随在一个包语句之后。不应该包含更多的代码或注释。

          如果要所有的源文件进行概述性注释,提供一个overview.html命名的HTML文档。这个文件位于包含所有源文件的父目录中。标记<BODY>···</BODY>之间的所有文本都会被抽取出来。

    三、文档注释和Html

    (一)html格式生成:

         生成的文档系html款式,而这些html款式的标识符并非javadoc加的,而是写诠释的时候写上去的。打个比方,需要换行时,不是敲入1个回车符,而是写入<br>,要是要分段,就该当在段前写入<p>。

         因而,格式化文档,不外乎在文档诠释中添加相应的html标签。

        文档注释的正文并非直接复制到输出文档(文档的html文档),而是读出每一行后,删掉前导的*号及*号从前的空格,再输入到文档的。

    (二).java文档中是这样的:

    1 /** *thisisfirstline.<br>
    2 *****thisissecondline.<br>
    3 thisisthirdline. 
    4 */

    (三)编译输出后的html源码则是:

    1 thisisfirstline.<br> 
    2 thisissecondline.<br> 
    3 thisisthirdline.

    (四)在网页上显示是这样的:

    thisisfirstline.
    thisissecondline.
    thisisthirdline.

    (五)说明:

         前导的*号准许持续运用不止一个,其成果和运用1个*号一致,但不止一个*号前不可有其它字符分隔,不然分隔符及背后的。*号都将作为文档的内容。*号在这里系作为左边陲运用,如上例的第一行和第二行;要是没有前导的*号,则边陲从第一个有效字符开端,而不包括前面的空格,如上例第四行。

    四、文档注释注意的细节

         文档诠释只阐明紧接其后的类、属性或者方式。

    (一)如下例:

    1 /**comment for class*/ 
    2 public class Test{ 
    3 /**comment for a attribute*/ 
    4 int number; 
    5 /**comment for a method*/ 
    6 public void mymethod(){......}
    7    ...... 
    8 } 

          上例中的三处诠释不外乎区别对类、属性和方式的文档诠释。它们生成的文档分别是阐明紧接其后的类、属性、方式的。“紧接”二字特别首要,要是忽视了这一点,就很可能造成生成的文档故障。

    (二)正确例子

    1 import java.lang.*; 
    2 /**comment for class*/ 
    3 public class Test{......} //此例为准确的例子 

    (三) 错误例子:

    1 /**comment for class*/ 
    2 importjava.lang.*; 
    3 public class Test{......} //此例为故障的例子 

          这个例子只把上例的import语句和文档诠释局部交换了位置,效果却不尽相同——生成的文档中基本就找不到上述诠释的内容了。

    (四) 错误原因:

          “/**comment for class*/”系对 Test类的阐明,把它放在“public class Test{......}”之前时,其后紧接着class Test,吻合限定,因此生成的文档准确。可是把它和“importjava.lang.*;”改换了位置后,其后紧接的不再是类Test了,而是一个import语句。因为文档诠释只能阐明类、属性和方式,import语句不在此列,因此这个文档诠释便被当成故障阐明省略掉了。

    五、文档注释的三个局部

         根据文档格式在网页上面的最终显示,文档注释分为三个部分:

    (一) 例子

     1 /**
     2      *该方法用来测量一段时间内的平均速度.
     3      *<p>啊啊啊啊啊啊<br>
     4      *<p>哈哈哈哈哈哈<br>
     5      *@param start 起始时间
     6      *@param end 截止时间
     7      *@return 返回int型变量
     8      *@exception java.lang.exceptionthrowwhenswitchis1
     9      */
    10     public int measureAverageSpeed(int start,int end ){
    11         int aspeed=12;
    12         return aspeed;
    13 }

    (二) 第一部分:简述。

         在Html显示中,会将属性和方法先进行概要列举,如图。

         上述例子中的第二句——*该方法用来测量一段时间内的平均速度.

         通过.来进行区分,在简述部分只显示.号之前的部分。如下图,measureAverageSpeed方法只显示了该方法用来测量一段时间内的平均速度.这句话,后面的“啊啊啊啊啊啊”“哈哈哈哈哈”都没有显示。

                           

    (三)第二部分:局部对属性或者方式进行仔细的阐明

         阐明java语句:

    1  *该方法用来测量一段时间内的平均速度.
    2  *<p>啊啊啊啊啊啊<br>
    3  *<p>哈哈哈哈哈哈<br>

        会包含简述中的语句,如下图:

     

    (四)第三部分:特殊说明

         java语句:

    1 *@param start 起始时间
    2 *@param end 截止时间
    3 *@return 返回int型变量
    4 *@exception java.lang.exceptionthrowwhenswitchis1

        如下图:

     

    六、运用javadoc记号

    (一) @see的运用

          1. 提供类名,方法名,变量名,javadoc在文档中插入一个超链接。如下:

              @see com.cn.corejava.BusTestJavaDoc#measureAverageSpeed(int)

              建立一个链接到com.cn.corejava.BusTestJavaDoc类的measureAverageSpeed(int)方法的超链接。

              注意:一定是#来分割类名和方法名或者类名和变量名。

          2. @see <a href="www.baidu.com">百度</a>

    (二) 运用@author、@version阐明类

    1. @author,可以不止一个
    2. 最好只有一个

    (三) 运用@param、@return和@exception阐明方式

    1. 这三个记号全是只用于方法的。@param描写方式的参数,@return描写方式的返回值,@exception描写方式也许抛出的异常。
    2. 每一个@param只能描写方式的1个参数,因此,要是方式需要不止一个参数,就需要不止一次运用@param来描写。
    3. @return如下代码:1个方式中只能用1个@return,要是文档阐明中列了不止一个@return,则javadoc编译时会发出正告,且只要第一个@return在生成的文档中有效只会生成第一个.如下,生成的只有第一个:
    1 *@return 返回int型变量
    2 *@return 返回double型变量

         4. 方法也许抛出的异常应该用@exception描写。因为一个方式也许抛出不止一个非常,因此可以有不止一个@exception

    七、Javadoc命令

    (一)Javadoc生成命令

    1. javadoc命令

            javadoc -d 文档寄存目录 -author -version java文档存在目录源文件名.java

             -author –version可以省略

         2. 举例子:

            java -d D:workspace8JavaDocsrc D:workspace8JavaDocsrcBusTestJavaDoc.java

         3. 如下图:

    (二)Javadoc帮助命令

         运行javadoc-help可以看到javadoc的用法,如下:

     

    【建议风格】

       一、 格式

    • 一般形式:

       这样:

    /**
     * Multiple lines of Javadoc text are written here,
     * wrapped normally...
     */
    public int method(String p1) { ... }

       或这样:

    /** An especially short bit of Javadoc. */
    •  段落

          空行(即,只包含最左侧星号的行)会出现在段落之间和Javadoc标记(@XXX)之前(如果有的话)。除了第一个段落,每个段落第一个单词前都有标签<p>,并且它和第一个单词间没有空格。

    • Javadoc标记

          标准的Javadoc标记按以下顺序出现:@param, @return, @throws, @deprecated, 前面这4种标记如果出现,描述都不能为空。当描述无法在一行中容纳,连续行需要至少再缩进4个空格。

    二、摘要片段

    •  每个类或成员的Javadoc以一个简短的摘要片段开始。这个片段是非常重要的,在某些情况下,它是唯一出现的文本,比如在类和方法索引中。
    •  这只是一个小片段,可以是一个名词短语或动词短语,但不是一个完整的句子。它不会以A {@code Foo} is a...或This method returns...开头, 它也不会是一个完整的祈使句,如Save the record...。然而,由于开头大写及被加了标点,它看起来就像是个完整的句子。
    • Tip:一个常见的错误是把简单的Javadoc写成/** @return the customer ID */,这是不正确的。它应该写成/** Returns the customer ID. */

    三、哪里需要使用Javadoc

       至少在每个public类及它的每个public和protected成员处使用Javadoc。

    例外:

    • 不言自明的方法

          对于简单明显的方法如getFoo,Javadoc是可选的(即,是可以不写的)。这种情况下除了    写“Returns the foo”,确实也没有什么值得写了。

          单元测试类中的测试方法可能是不言自明的最常见例子了,我们通常可以从这些方法的描述性命名中知道它是干什么的,因此不需要额外的文档说明。

    • 重载

          如果一个方法重载了超类中的方法,那么Javadoc并非必需的。

    • 可选的Javadoc

          对于包外不可见的类和方法,如有需要,也是要使用Javadoc的。如果一个注释是用来定义一个类,方法,字段的整体目的或行为,那么这个注释应该写成Javadoc,这样更统一更友好。

    【参考资料】

    1. 这篇文章主要是学习了《javadoc__用法_很详细》这个文档

    【后面的话】

         加油吧。

    ——TT

  • 相关阅读:
    poj 3321 Apple Tree
    hdu 1520 Anniversary party
    Light OJ 1089 Points in Segments (II)
    Timus 1018 Binary Apple Tree
    zoj 3299 Fall the Brick
    HFUT 1287 法默尔的农场
    Codeforces 159C String Manipulation 1.0
    GraphQL + React Apollo + React Hook 大型项目实战(32 个视频)
    使用 TypeScript & mocha & chai 写测试代码实战(17 个视频)
    GraphQL + React Apollo + React Hook + Express + Mongodb 大型前后端分离项目实战之后端(19 个视频)
  • 原文地址:https://www.cnblogs.com/xt0810/p/3630996.html
Copyright © 2011-2022 走看看