《4.2.2文档诠释的三局部》由会员分享，可在线阅读，更多相关《4.2.2文档诠释的三局部（21页珍藏版）》请在金锄头文库上搜索。
1、 一一 申明申明 . 2 二二 JAVADOC 简介简介 . 2 三三 例子：例子： . 3 四 JAVADOC 命令对注释规范的详细介绍四 JAVADOC 命令对注释规范的详细介绍 . 4 4.1 JAVA文档和JAVADOC . 5 4.2 文档诠释的款式 . 5 4.2.1文档和文档诠释的格式化 . 6 4.2.2 文档诠释的三局部 . 8 4.2.3 运用javadoc记号 . 10 4.2.3.1 see的运用 . 10 4.2.3.2 运用author、version阐明类 . 14 4.2.3.3 运用param、return和exception阐明方式 . 15 以下几点还须再
2、次注意 . 17 五五 JAVADOC命令命令 . 18 一一 申明申明 以下内容 sort by mang 大量参考引用了http:/ 中的内容，对作者致以最猛列的感谢 二二 javadoc 简介简介 我们知道 Java 中有三种注释语句： 1./用于单行注释。 2./*.*/用于多行注释，从/*开始，到*/结束，不能嵌套。 3./*.*/则是为支持 jdk 工具 javadoc.exe 而特有的注释语句。 javadoc 工具能从 java 源文件中读取第三种注释， 并能识别注释中用标识的一些特殊变量 （见表） ， 制作成 Html 格式的类说明文档。javadoc 不但能对一个 java
3、 源文件生成注释文档，而且能对目录和包生成交叉链接的 html 格式的类说明文档，十分方便。 注释中可以出现的关键字，以开头： author 作者名 version 版本标识 parameter 参数名及其意义 since 最早出现的 JDK 版本 return 返回值 throws 异常类及抛出条件 deprecated 引起不推荐使用的警告 see 交叉参考 三三 例子：例子： 以下是一个关于汽车类的例子，来具体说明运用 javadoc 命令时对注释的规范 汽车类有 4 个属性：maxSpeed averageSpeed waterTemperature Temperature 分别用来表
4、示最大速度，平均速度，水温 室温 有 2 个方法 measureAverageSpeed() measureMaxSpeed() 用来测量汽车的平均速度和最大速度 以下例子基本包括了 javadoc 中常用到的注释，下面的篇幅中会一一详细说明的， 读者可以试着用 javadoc 命令生成以下例子的说明文档 /* *汽车类的简介 *汽车类具体阐述第一行 *汽车类具体阐述第二行 *author man *author man2 *version 1.0 *see ship *see aircraft */ public class Bus /* *用来标识汽车行驶当中最大速度 *see #aver
5、ageSpeed */ public int maxSpeed; /*用来标识汽车行驶当中平均速度*/ public int averageSpeed; /*用来标识汽车行驶当中的水温*/ public int waterTemperature; /*用来标识天气温度*/ public int Temperature; Bus() /* *该方法用来测量一段时间内的平均速度 *param start 起始时间 *param end 截止时间 *return 返回 int 型变量 *exception java.lang.exceptionthrowwhenswitchis1 */ public
6、 int measureAverageSpeed(int start,int end ) int aspeed=12; return aspeed; /* *该方法用来测量最大速度 */ public int measureMaxSpeed() 四 javadoc 命令对注释规范的详细介绍 四 javadoc 命令对注释规范的详细介绍 只有/*/这样的诠释才能被写入 javadoc 文档。 只有/*/这样的诠释才能被写入 javadoc 文档。 4.1 java文档和文档和javadoc 在 jdk 的 bin 目录下你可以找到 javadoc，如果是 windows 下的jdk，它的文件名为
7、 javadoc.exe。运用 javdoc 编译 .java 源文件时，它会读出 java 源文件中的文档诠释，并遵照一定的限定和java 源程序一起进行编译，生成文档。 引见 javadoc 的编译命令之前，还是先懂得一下文档诠释的款式吧。不过为了能够编译下面提到若干例子，这里先引见一条javadoc 命令： javadoc -d 文档寄存目录 -author -version 源文件名.java 这条命令编译 1 个名为“源文件名.java”的 java 源文件，并将生成的文档存放在“文档寄存目录”指定的目录下，生成的文档中 index.html 不外乎是文档的首页。-author 和-
8、version 二上选项可以省略。 4.2 文档诠释的款式文档诠释的款式 文档诠释可以用于对类、属性、方式等进行阐明文档诠释可以用于对类、属性、方式等进行阐明。写文档诠释时除了需要运用/*.*/规定之外，还需要注意诠释内部的有些细节毛病。 4.2.1 文档和文档诠释的格式化文档和文档诠释的格式化 生成的文档系 html 款式，而这些 html 款式的标识符并非javadoc 加的，而是咱们在写诠释的时候写上去的。打个比方，需要换行时， 不是敲入 1 个回车符， 而是写入br， 要是要分段，就该当在段前写入p。 因而，格式化文档，不外乎在文档诠释中添加相应的 html 标签。 文档诠释的正文并非
9、直接复制到输出文档(文档的html文档)，而是读出每一行后，删掉前导的*号及*号从前的空格，再输入到文档的。如 /* *thisisfirstline.br *thisissecondline.br thisisthirdline. */ 编译输出后的 html 源码则是 thisisfirstline.br thisissecondline.br thisisthirdline. 前导的*号准许持续运用不止一个，其成果和运用 1 个*号一致，但不止一个*号前不可有其它字符分隔，不然分隔符及背后的*号都将作为文档的内容。*号在这里系作为左边陲运用，如上例的第一行和第二行；要是没有前导的*号，则
10、边陲从第一个有效字符开端，而不包括前面的空格而不包括前面的空格，如上例第四行。 还有一点需要阐明，文档诠释只阐明紧接其后的类、属性或者方式文档诠释只阐明紧接其后的类、属性或者方式。如下例： /*comment for class*/ public class Test /*comment for a attribute*/ int number; /*comment for a method*/ public void mymethod(). . 上例中的三处诠释不外乎区别对类、属性和方式的文档诠释。它们生成的文档分别是阐明紧接其后的类、属性、方式的。“紧接紧接”二字特别首要，要是忽视了这一点
11、，就很可能造成生成的文档故障。如 import java.lang.*; /*comment for class*/ public class Test. /此例为准确的例子 这个文档诠释将生成准确的文档。但只需要转变其中两行的位置，化成下例，就会出错： /*comment for class*/ importjava.lang.*; public class Test. /此例为故障的例子 这个例子只把上例的import语句和文档诠释局部交换了位置，效果却不尽相同生成的文档中基本就找不到上述诠释的内容了。缘故何在？ “/*comment for class*/”系对 Test 类的阐明，把它
12、放在“public class Test.”之前时， 其后紧接着class Test，吻合限定，因此生成的文档准确。可是把它和“importjava.lang.*;”改换了位置后，其后紧接的不再是类Test 了，而是一个 import 语句。因为文档诠释只能阐明类、属性和方式，import 语句不在此列，因此这个文档诠释便被当成故障阐明省略掉了。 4.2.2 文档诠释的三局部文档诠释的三局部 依据在文档中卖弄的成果，文档诠释分为三局部。先举例如下，以便阐明。 /* *汽车类的简述. *汽车类具体阐述第一行 *汽车类具体阐述第二行 *author man *author man2 *version 1.0 *see ship *see aircraft */ public class Bus /类中的语句 第一部分系简述，也就是注释中的的第二行。文档中，关于属性和方式全是先有一个列表，然后才在背后一个一个的仔细的阐明。列表中属性名或者方法名背后那段阐明不外乎简述。 简述局部写在一段文档诠释的最前面，第一个点号(.)之前(包含点号)。换句话说，不外乎用第
