Java核心技术第4章(9)
2015-10-07 16:49
344 查看
4.9 文档注释
JDK包含一个很有用的工具,叫做javadoc,它可以由源文件生成一个HTML文档.如果将文档存入一个独立的文件中,就有可能会随着时间的推移,出现代码和注释不一致的问题.然而,由于文档注释与源代码在同一个文件中,修改源代码的同时,重新运行javadoc就可以轻而易举地保持两者的一致性.
4.9.1 注释的插入
javadoc实用程序(utility)从下面几个特性中抽取信息:包
公有类与接口
公有的和受保护的构造器及方法
公有的和受保护的域
应该为上面几个部分编写注释.注释应该设置在所描述特性的前面.
每个/** ... */ 文档注释在标记之后紧跟着自由格式文本.标记由@开始,如@author或@param .
4.9.2 类注释
类注释必须在 import 语句之后,类定义之前下面是一个类注释的例子:
/** * A <code>Card</code> object represents a playing card */ public class Card { ... }
4.9.3 方法注释
每一个方法注释必须放在所描述的方法之前.除了通用标记之外,还可以使用下面的标记:@param 变量描述
这个标记将对当前方法的"param"部分添加一个条目,一个方法的所有@param 标记必须放在一起.
@return 描述
这个标记将对当前方法添加"return"部分.
@throws 类描述
这个标记将添加一个注释,用于表示这个方法有可能抛出异常
下面是一个方法注释的示例:
/** * Raises the salary of an employee * @param byPercent the percentage by which to raise the salary * @return the amount of the raise */ public double raiseSalary(double byPercent) { double raise = salary * byPercent / 100; salary += raise; return raise; }
4.9.4 域注释
只需要对公有域(通常指的是静态常量)建立文档.例如:/** * The "Hearts" card suit */ public static final int HEARTS = 1;
4.9.5 通用注释
用在类文档的注释中.4.9.6 包与概述注释
可以直接将类,方法和变量的注释放置在java源文件中.4.9.7 注释的抽取
这里,假设HTML文件将被存放在目录docDirectory下.执行以下步骤:1.切换到包含想要生成文档的源文件目录.
2.如果是个包,应该运行命令:
javadoc -d docDirectory nameofPackage如果是类,则运行命令:
javadoc -d docDirectory nameofClass(Name.java)如果省略了-d docDirectory选项,那么HTML文件就会被提取到当前目录下.
相关文章推荐
- Java核心技术第4章(8)
- Intellij Idea 将java项目打包成jar
- [Java]collection类集中的Set接口
- Java Web 中使用ffmpeg实现视频转码、视频截图
- hadoop eclipse windows
- 【开启Java之旅】
- Java中this关键字
- java各变量的存储位置
- Struts 1.x 工作流程 附第一个Struts 1.x实例讲解
- spring mvc自定义过滤器filter实现对请求参数编解码的代码
- [转] Java中native关键字
- Spring MVC+Spring+Hibrenarte实现的简单的CRUD项目实例
- java笔记--Java内存模型与线程
- spring 使用外部配置文件访问数据库
- Java构造函数(面向对象)
- java中的final关键字
- 深入解析Java编程中面向字节流的一些应用
- 在springmvc中解决FastJson循环引用的问题
- SpringMVC与fastjson整合并同时解决中文乱码问题
- SpringMVC处理ajax请求