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

4. eclipse中导出Html文档：

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

二、javadoc的几种注释

(一)类注释

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

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

(二)方法注释

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

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

(三)域注释

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

  1. 1 /**
  2. 2     *用来标识汽车行驶当中最大速度
  3. 3     *@see #averageSpeed
  4. 4     */
  5. 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. 1 /** *thisisfirstline.<br>
  2. 2 *****thisissecondline.<br>
  3. 3 thisisthirdline.
  4. 4 */

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

  1. 1 thisisfirstline.＜br＞
  2. 2 thisissecondline.＜br＞
  3. 3 thisisthirdline.

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

  1. thisisfirstline.
  2. thisissecondline.
  3. thisisthirdline.

(五)说明：

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

四、文档注释注意的细节

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

(一)如下例：

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

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

(二)正确例子

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

(三) 错误例子：

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

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

(四) 错误原因：

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

五、文档注释的三个局部

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

(一) 例子

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

(二) 第一部分：简述。

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

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

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

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

阐明java语句：

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

会包含简述中的语句，如下图：

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

java语句：

  1. 1 *@param start 起始时间
  2. 2 *@param end 截止时间
  3. 3 *@return 返回int型变量
  4. 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. 1 *@return 返回int型变量
  2. 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的用法，如下：

【建议风格】

一、 格式

  • 一般形式：

这样：

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

或这样：

  1. /** 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学习笔记和可能的注意细节的更多相关文章

  1. Java学习笔记（十五）——javadoc学习笔记和可能的注意细节

    [前面的话] 这次开发项目使用jenkins做持续集成,PMD检查代码,Junit做单元测试,还会自动发邮件通知编译情况,会将javadoc生成的文档自动发到一个专门的服务器上面,每个人都可以看,所以 ...

  2. [转载]Log4net学习笔记

    Log4net 学习笔记: 主要是根据apache站点整理的: 原文链接:http://logging.apache.org/log4net/release/sdk/ http://logging.a ...

  3. [转载]pytest学习笔记

    pytest学习笔记(三)   接着上一篇的内容,这里主要讲下参数化,pytest很好的支持了测试函数中变量的参数化 一.pytest的参数化 1.通过命令行来实现参数化 文档中给了一个简单的例子, ...

  4. 转载-python学习笔记之输入输出功能读取和写入数据

    读取.写入和 Python 在 “探索 Python” 系列以前的文章中,学习了基本的 Python 数据类型和一些容器数据类型,例如tuple.string 和 list.其他文章讨论了 Pytho ...

  5. 转载-Python学习笔记之文件读写

    Python 文件读写 Python内置了读写文件的函数,用法和C是兼容的.本节介绍内容大致有:文件的打开/关闭.文件对象.文件的读写等. 本章节仅示例介绍 TXT 类型文档的读写,也就是最基础的文件 ...

  6. 转载——JavaScript学习笔记：取数组中最大值和最小值

    转载自:http://www.w3cplus.com/javascript/calculate-the-max-min-value-from-an-array.html. 取数组中最大值 可以先把思路 ...

  7. 转载-python学习笔记之文件I/O

    Python 文件I/O 本章只讲述所有基本的的I/O函数,更多函数请参考Python标准文档. 打印到屏幕 最简单的输出方法是用print语句,你可以给它传递零个或多个用逗号隔开的表达式.此函数把你 ...

  8. 转载-python学习笔记之常用模块用法分析

    内置模块(不用import就可以直接使用)   常用内置函数   help(obj) 在线帮助, obj可是任何类型 callable(obj) 查看一个obj是不是可以像函数一样调用 repr(ob ...

  9. [转载]AngularJS学习笔记

    http://www.zouyesheng.com/angular.html 关于AngularJS 关于本文档 开始的例子 依赖注入 作用域 数据绑定与模板 6.1. 数据->模板 6.2. ...

随机推荐

  1. Android中检测软键盘的弹出和关闭

    Android系统并没有提供明显的API来监听软键盘的弹出和关闭,但是在某些情况下我们还是有办法来检测软键盘的弹出和关闭. 从StackOverflow找到了一个不错的方法.但是这种只适用于在mani ...

  2. 错排-HDU 2049 递推的应用

    当n个编号元素放在n个编号位置,元素编号与位置编号各不对应的方法数用M(n)表示,那么M(n-1)就表示n-1个编号元素放在n-1个编号位置,各不对应的方法数,其它类推. 第一步,把第n个元素放在一个 ...

  3. SQL 两表关联查询 where 条件中等号两端字段顺序对效率的影响

    现有两表A(大).B(小)作关联查询,SQL语句如下: SQL1:select * from A,B where A.id = B.id SQL2:select * from A,B where B. ...

  4. redis beforesleep

    本来想把redis main函数附带都读完再写笔记,但实在太大了,所以现在决定一部分一部分地记录. eventloop中在每次进入循环时都会调用beforeSleep回调(因为processevent ...

  5. message from server: "Host 'xxx' is not allowed to connect to this MySQL server的解决

    解决方法:    1. 改表法.    可能是你的帐号不允许从远程登陆,只能在localhost.这个时候只要在localhost的那台电脑,登入mysql后,更改 "mysql" ...

  6. C++中的异常

    一,异常的推演 1.函数与异常 平时我们在函数中出现异常情况时通常通过return终止函数并返回一个值,然后在函数上层来获取值并判断是什么异常情况.因为函数是栈结构的,所以return的时候是通过栈结 ...

  7. Git安装使用

    转载:http://www.open-open.com/lib/view/open1414396787325.html 1.window版地址 https://git-for-windows.gith ...

  8. 【锋利的Jquery】读书笔记七

    第七章  jquery插件 管理cookie的插件--cookie jquery插件太多没什么好讲的,百度太多 说以下 cookie插件 <!DOCTYPE html> <html& ...

  9. Maven之（四）Maven命令

    常用命令 从某种意义上来说,软件是帮助不懂程序的人来操作计算机的,图形化界面尤其如此.在上个世纪,比尔盖茨之所以成为世界首富,微软之所以IT界的巨鳄,就是因为Windows开图形化操作之先河,并抢先占 ...

  10. MyEclipse 代码提示设置

    打开 Eclipse -> Window -> Perferences -> Java -> Editor -> Content Assist,在右边最下面一栏找到 au ...