Java学习笔记（十五）——javadoc学习笔记和可能的注意细节
【前面的话】
这次开发项目使用jenkins做持续集成，PMD检查代码，Junit做单元测试，还会自动发邮件通知编译情况，会将javadoc生成的文档自动发到一个专门的服务器上面，每个人都可以看，所以搞得我还必须好好学习一下JavaDoc，别人看到也可以美观一点。
【基础知识】
一、JavaDoc简介And基础知识
(一) Java注释类型
- //用于单行注释。
- /*...*/用于多行注释，从/*开始，到*/结束，不能嵌套。
- /**...*/则是为支持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例子：
/**
*汽车类的简介
*<p>汽车类具体阐述第一行<br>
*汽车类具体阐述第二行
*@author man
*@author man2
*@version 1.0
*@see ship
*@see aircraft
*/
public class BusTestJavaDoc{
/**
*用来标识汽车行驶当中最大速度
*@see #averageSpeed
*/
public int maxSpeed;
/**用来标识汽车行驶当中平均速度*/
public int averageSpeed;
/**用来标识汽车行驶当中的水温*/
public int waterTemperature;
/**用来标识天气温度*/
public int Temperature;
BusTestJavaDoc(){ }
/**
*该方法用来测量一段时间内的平均速度
*@param start 起始时间
*@param end 截止时间
*@return 返回int型变量
*@exception java.lang.exceptionthrowwhenswitchis1
*/
public int measureAverageSpeed(int start,int end ){
int aspeed=12;
return aspeed;
}
/**
* 该方法用来测量最大速度
*/
public int measureMaxSpeed(){
return maxSpeed; }
}
4. eclipse中导出Html文档：
export——java——javadoc——选择存储位置，可以看看生产的Javadoc
二、javadoc的几种注释
(一)类注释
类注释出现在import语句之后，类定义之前，可以使用通用注释，如下：
/**
*汽车类的简介
*<p>汽车类具体阐述第一行<br>
*汽车类具体阐述第二行
*@author man
*@author man2
*@version 1.0
*@see ship
*@see aircraft
*/
public class BusTestJavaDoc{
}
(二)方法注释
每一个方法注释必须放在所描述的方法之前，除了使用通用注释，还可以使用方法注释。如下：
/**
*该方法用来测量一段时间内的平均速度
*@param start 起始时间
*@param end 截止时间
*@return 返回int型变量
*@exception java.lang.exceptionthrowwhenswitchis1
*/
public int measureAverageSpeed(int start,int end ){
int aspeed=12;
return aspeed;
}
(三)域注释
只需对公有域进行注释，可以使用通用注释，如下：
/**
*用来标识汽车行驶当中最大速度
*@see #averageSpeed
*/
public int maxSpeed;
(四)包注释与概述注释
对于类，方法，变量的注释放置在Java源文件中就可以了，只需使用/**···*/文档注释界定就可以了，如果要对包进行注释，需要在每一个包目录中添加一个单独的文件。如下:
- 提供一个package.html命名的HTML文档。标记<BODY>···</BODY>之间的所有文本都会被抽取出来。
- 提供一个package-info.java命名的java文件。这个文件必须包含一个初始的以/**和*/界定的javadoc注释，跟随在一个包语句之后。不应该包含更多的代码或注释。
如果要所有的源文件进行概述性注释，提供一个overview.html命名的HTML文档。这个文件位于包含所有源文件的父目录中。标记<BODY>···</BODY>之间的所有文本都会被抽取出来。
三、文档注释和Html
(一)html格式生成：
生成的文档系html款式，而这些html款式的标识符并非javadoc加的，而是写诠释的时候写上去的。打个比方，需要换行时，不是敲入1个回车符，而是写入＜br＞，要是要分段，就该当在段前写入＜p＞。
因而，格式化文档，不外乎在文档诠释中添加相应的html标签。
文档注释的正文并非直接复制到输出文档(文档的html文档)，而是读出每一行后，删掉前导的*号及*号从前的空格，再输入到文档的。
(二).java文档中是这样的：
/** *thisisfirstline.<br>
*****thisissecondline.<br>
thisisthirdline.
*/
(三)编译输出后的html源码则是：
thisisfirstline.＜br＞
thisissecondline.＜br＞
thisisthirdline.
(四)在网页上显示是这样的：
thisisfirstline.
thisissecondline.
thisisthirdline.
(五)说明：
前导的*号准许持续运用不止一个，其成果和运用1个*号一致，但不止一个*号前不可有其它字符分隔，不然分隔符及背后的。*号都将作为文档的内容。*号在这里系作为左边陲运用，如上例的第一行和第二行；要是没有前导的*号，则边陲从第一个有效字符开端，而不包括前面的空格，如上例第四行。
四、文档注释注意的细节
文档诠释只阐明紧接其后的类、属性或者方式。
(一)如下例：
/**comment for class*/
public class Test{
/**comment for a attribute*/
int number;
/**comment for a method*/
public void mymethod(){......}
......
}
上例中的三处诠释不外乎区别对类、属性和方式的文档诠释。它们生成的文档分别是阐明紧接其后的类、属性、方式的。“紧接”二字特别首要，要是忽视了这一点，就很可能造成生成的文档故障。
(二)正确例子
import java.lang.*;
/**comment for class*/
public class Test{......} //此例为准确的例子
(三) 错误例子：
/**comment for class*/
importjava.lang.*;
public class Test{......} //此例为故障的例子
这个例子只把上例的import语句和文档诠释局部交换了位置，效果却不尽相同——生成的文档中基本就找不到上述诠释的内容了。
(四) 错误原因：
“/**comment for class*/”系对 Test类的阐明，把它放在“public class Test{......}”之前时，其后紧接着class Test，吻合限定，因此生成的文档准确。可是把它和“importjava.lang.*;”改换了位置后，其后紧接的不再是类Test了，而是一个import语句。因为文档诠释只能阐明类、属性和方式，import语句不在此列，因此这个文档诠释便被当成故障阐明省略掉了。
五、文档注释的三个局部
根据文档格式在网页上面的最终显示，文档注释分为三个部分：
(一) 例子
/**
*该方法用来测量一段时间内的平均速度.
*<p>啊啊啊啊啊啊<br>
*<p>哈哈哈哈哈哈<br>
*@param start 起始时间
*@param end 截止时间
*@return 返回int型变量
*@exception java.lang.exceptionthrowwhenswitchis1
*/
public int measureAverageSpeed(int start,int end ){
int aspeed=12;
return aspeed;
}
(二) 第一部分：简述。
在Html显示中，会将属性和方法先进行概要列举，如图。
上述例子中的第二句——*该方法用来测量一段时间内的平均速度.
通过.来进行区分，在简述部分只显示.号之前的部分。如下图，measureAverageSpeed方法只显示了该方法用来测量一段时间内的平均速度.这句话，后面的“啊啊啊啊啊啊”“哈哈哈哈哈”都没有显示。
(三)第二部分：局部对属性或者方式进行仔细的阐明
阐明java语句：
*该方法用来测量一段时间内的平均速度.
*<p>啊啊啊啊啊啊<br>
*<p>哈哈哈哈哈哈<br>
会包含简述中的语句，如下图：
(四)第三部分：特殊说明
java语句：
*@param start 起始时间
*@param end 截止时间
*@return 返回int型变量
*@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阐明类
- @author,可以不止一个
- 最好只有一个
(三) 运用@param、@return和@exception阐明方式
- 这三个记号全是只用于方法的。@param描写方式的参数，@return描写方式的返回值，@exception描写方式也许抛出的异常。
- 每一个@param只能描写方式的1个参数，因此，要是方式需要不止一个参数，就需要不止一次运用@param来描写。
- @return如下代码：1个方式中只能用1个@return，要是文档阐明中列了不止一个@return，则javadoc编译时会发出正告，且只要第一个@return在生成的文档中有效只会生成第一个.如下,生成的只有第一个:
*@return 返回int型变量
*@return 返回double型变量
4. 方法也许抛出的异常应该用@exception描写。因为一个方式也许抛出不止一个非常，因此可以有不止一个@exception
七、Javadoc命令
(一)Javadoc生成命令
- 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，这样更统一更友好。
【参考资料】
- 这篇文章主要是学习了《javadoc__用法_很详细》这个文档
【后面的话】
加油吧。
——TT
Java学习笔记（十五）——javadoc学习笔记和可能的注意细节的更多相关文章
- 201871010106-丁宣元 《面向对象程序设计（java)》第十五周学习总结
201871010106-丁宣元 <面向对象程序设计(java)>第十五周学习总结 正文开头: 项目 内容 这个作业属于哪个课程 https://home.cnblogs.com/u/nw ...
- 马凯军201771010116《面向对象与程序设计Java》第十五周学习知识总结
实验十五 GUI编程练习与应用程序部署 一.知识学习部分 清单文件 每个JAR文件中包含一个用于描述归档特征的清单文件(manifest).清单文件被命名为MANIFEST.MF,它位于JAR文件的 ...
- 2017面向对象程序设计（Java）第十五周学习总结
上周,老师要求同学们自学应用程序部署,并布置了相关的实验任务.此次实验的目的是掌握Java应用程序的打包操作:了解应用程序存储配置信息的两种方法: 了解Applet小应用程序的开发及应用方法:掌握基于 ...
- 201871010126 王亚涛 《面向对象程序设计 Java》 第十五周学习总结
内容 这个作业属于哪个课程 https://www.cnblogs.com/nwnu-daizh/ 这个作业的要求在哪里 https://www.cnblogs.com/nwnu-daizh/p/11 ...
- 201871010109-胡欢欢 《面向对象程序设计（java)》第十五周学习总结
正文开头: 项目 内容 这个作业属于哪个课程 https://home.cnblogs.com/u/nwnu-daizh/ 这个作业的要求在哪里 https://www.cnblogs.com/nwn ...
- 201871010101-陈来弟《面向对象程序设计（java)》第十五周学习总结
...
- 201871010118-唐敬博 《面向对象程序设计（java)》第十五周学习总结
博文正文开头格式:(2分) 项目 内容 这个作业属于哪个课程 <https://www.cnblogs.com/nwnu-daizh/> 这个作业的要求在哪里 <https://ww ...
- 201771010128王玉兰《面向对象与程序设计（java）第十五周学习总结》
第一部分:理论知识 一:JAR文件 Java程序的打包:程序编译完成后,程序员 将.class文件压缩打包为.jar文件后,GUI界面 程序就可以直接双击图标运行. jar文件(Java归档)既可以包 ...
- GUI学习之十五——QAbstractSpinBox学习总结
QAbstractSpinBox是一个抽象类,是将所有步长调节器的通用的功能抽象出了一个父类.虽然QAbstractSpinBox是一个抽象类,但是可以直接实例化使用.QAbstractSpinBox ...
- python3.4学习笔记(十五) 字符串操作（string替换、删除、截取、复制、连接、比较、查找、包含、大小写转换、分割等）
python3.4学习笔记(十五) 字符串操作(string替换.删除.截取.复制.连接.比较.查找.包含.大小写转换.分割等) python print 不换行(在后面加上,end=''),prin ...
随机推荐
- 读书笔记——Windows核心编程（8）Interlocked系列函数
先让我们来复习下小学知识 A+B=C//式中A为被加数,B为加数. A-B=C//式中A为被减数,B为减数. 再让我们来明确一个知识点:返回值为void的Windows函数意味着一定会执行成功. -- ...
- python中列表和元组以及字符串的操作
python中列表是非常好用的.不过有一些使用小细节还需要注意一下. tag[32:-4] 从index为32到tag的倒数第4个字符. 如果索引为32的值在倒数第4个字符的右边,那么将输出为空.只要 ...
- Linux Crash/Hang on Bay Trail/J1900/N2940
近几年的linux kernel, 尤其是4.1以后,在Bay Trail平台上会随机挂起和死机,亲测j1900,死机非常频繁,而且死机前毫无征兆,直接就挂起了,console也没有相应. 这个问题在 ...
- shell读取文件每一行的方式
1.使用read命令读取一行数据 while read myline do echo "LINE:"$myline done < datafile.txt 2.使用read命 ...
- 给Apache增加SSI支持（shtml的奥秘）
什么是SSI? SSI是英文Server Side Includes的缩写,翻译成中文就是服务器端包含的意思.从技术角度上说,SSI就是在HTML文件中,可以通过注释行调用的命令或指针.SSI具有强大 ...
- POJ 2406 Power Strings (KMP)
Power Strings Time Limit: 3000MSMemory Limit: 65536K Total Submissions: 29663Accepted: 12387 Descrip ...
- REDIS 在电商中的实际应用场景(转）
1. 各种计数,商品维度计数和用户维度计数 说起电商,肯定离不开商品,而附带商品有各种计数(喜欢数,评论数,鉴定数,浏览数,etc),Redis的命令都是原子性的,你可以轻松地利用INCR,DECR等 ...
- Oracle 分组聚合二种写法，listagg和wmsys.wm_concat
with temp as( select 'China' nation ,'Guangzhou' city from dual union all select 'China' nation ,'Sh ...
- [转]JQuery Ajax 在asp.net中使用总结
本文转自:http://www.cnblogs.com/acles/articles/2385648.html 自从有了JQuery,Ajax的使用变的越来越方便了,但是使用中还是会或多或少的出现一些 ...
- 《MapReduce: Simplified Data Processing on Large Cluster 》翻译
Abstract MapReduce是一种编程模型和一种用来处理和产生大数据集的相关实现.用户定义map函数来处理key/value键值对来产生一系列的中间的key/value键值对.还要定义一个re ...