码迷,mamicode.com
首页 > 编程语言 > 详细

【转载】javadoc学习笔记和可能的注意细节

时间:2015-10-14 14:07:59      阅读:286      评论:0      收藏:0      [点我收藏+]

标签:

转载自:http://www.cnblogs.com/xt0810/p/3630996.html

【前面的话】

      这次开发项目使用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:\workspace8\JavaDoc\src D:\workspace8\JavaDoc\src\BusTestJavaDoc.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__用法_很详细》这个文档

【后面的话】

     加油吧。

 

【转载】javadoc学习笔记和可能的注意细节

标签:

原文地址:http://www.cnblogs.com/xWanted/p/4877152.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!