一 Java 文档
// 注释一行
/* */ 注释若干行
/** */ 注释若干行并写入 javadoc 文档
通常这种注释的多行写法如下
/**
*
*
*/
javadoc d 文档存放目录 author version 源文件名java
这条命令编译一个名为 源文件名java的 java 源文件并将生成的文档存放在文档存放目录指定的目录下生成的文档中 l 就是文档的首页author 和 version 两个选项可以省略
二 文档注释的格式
文档和文档注释的格式化
生成的文档是 HTML 格式而这些 HTML 格式的标识符并不是 javadoc 加的而是我们在写注释的时候写上去的
比如需要换行时不是敲入一个回车符而是写入 <br>如果要分段就应该在段前写入 <p>
文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件)而是读取每一行后删掉前导的 * 号及 * 号以前的空格再输入到文档的如
/**
* This is first line <br>
***** This is second line <br>
This is third line
*/
文档注释的三部分
先举例如下
/**
* show 方法的简述
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true 表示显示false 表示隐藏
* @return 没有返回值
*/
public void show(boolean b) {
frameshow(b);
}
第一部分是简述文档中对于属性和方法都是先有一个列表然后才在后面一个一个的详细的说明
简述部分写在一段文档注释的最前面第一个点号 () 之前 (包括点号)换句话说就是用第一个点号分隔文档注释之前是简述之后是第二部分和第三部分
第二部分是详细说明部分该部分对属性或者方法进行详细的说明在格式上没有什么特殊的要求可以包含若干个点号
* show 方法的简述
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
简述也在其中这一点要记住了
第三部分是特殊说明部分这部分包括版本说明参数说明返回值说明等
* @param b true 表示显示false 表示隐藏
* @return 没有返回值
三 使用 javadoc 标记
javadoc 标记由@及其后所跟的标记类型和专用注释引用组成
javadoc 标记有如下一些
@author 标明开发该类模块的作者
@version 标明该类模块的版本
@see 参考转向也就是相关主题
@param 对方法中某参数的说明
@return 对方法返回值的说明
@exception 对方法可能抛出的异常进行说明
@author 作者名
@version 版本号
其中@author 可以多次使用以指明多个作者生成的文档中每个作者之间使用逗号 () 隔开@version 也可以使用多次只有第一次有效
使用 @param@return 和 @exception 说明方法
这三个标记都是只用于方法的@param 描述方法的参数@return 描述方法的返回值@exception 描述方法可能抛出的异常它们的句法如下
@param 参数名 参数说明
@return 返回值说明
@exception 异常类名 说明
四 javadoc 命令
用法
javadoc [options] [packagenames] [sourcefiles]
选项
public 仅显示 public 类和成员
protected 显示 protected/public 类和成员 (缺省)
package 显示 package/protected/public 类和成员
private 显示所有类和成员
d <directory> 输出文件的目标目录
version 包含 @version 段
author 包含 @author 段
splitindex 将索引分为每个字母对应一个文件
windowtitle <text> 文档的浏览器窗口标题
javadoc 编译文档时可以给定包列表也可以给出源程序文件列表例如在 CLASSPATH 下有两个包若干类如下
fancyEditor
fancyTest
fancyeditorECommand
fancyeditorEDocument
fancyeditorEView
可以直接编译类
javadoc fancy\Testjava fancy\Editorjava fancy\editor\ECommandjava fancy\editor\EDocumentjava fancy\editor\EViewjava
也可以是给出包名作为编译参数如javadoc fancy fancyeditor
可以自己看看这两种方法的区别
到此为止javadoc就简单介绍完了想要用好她还是要多用多参考标准java代码
Java代码规范
注释
@author LEI
@version
注释文档的格式
注释文档将用来生成HTML格式的代码报告所以注释文档必须书写在类域构造函数方法定义之前注释文档由两部分组成描述块标记
例如
/**
* The doGet method of the servlet
* This method is called when a form has its tag value method equals to get
*
* @param request
* the request send by the client to the server
* @param response
* the response send by the server to the client
* @throws ServletException
* if an error occurred
* @throws IOException
* if an error occurred
*/
public void doGet (HttpServletRequest request HttpServletResponse response)
throws ServletException IOException {
doPost(request response);
}
前两行为描述描述完毕后由@符号起头为块标记注视
注释的种类
文件头注释
文件头注释以 /*开始以*/结束需要注明该文件创建时间文件名命名空间信息
例如
/*
* Created on
* /
类接口注释
类接口的注释采用 /** … */描述部分用来书写该类的作用或者相关信息块标记部分必须注明作者和版本
例如
/**Title: XXXX DRIVER
*Description: XXXX DRIVER
*Copyright: Copyright (c)
*Company:XXXX有限公司
*
* @author Java Development Group
* @version
*/
例如
/**
* A class representing a window on the screen
* For example:
*
* Window win = new Window(parent);
* winshow();
*
*
* @author Sami Shaio
* @version %I% %G%
* @see javaawtBaseWindow
* @see javaawtButton
*/
class Window extends BaseWindow {
}
构造函数注释
构造函数注释采用 /** … */描述部分注明构造函数的作用不一定有块标记部分
例如
/**
* 默认构造函数
*/
有例如
/**
* 带参数构造函数初始化模式名名称和数据源类型
*
* @param schema
* Ref 模式名
* @param name
* Ref 名称
* @param type
* byVal 数据源类型
*/
域注释
域注释可以出现在注释文档里面也可以不出现在注释文档里面用/** … */的域注释将会被认为是注释文档热出现在最终生成的HTML报告里面而使用/* … */的注释会被忽略
例如
/* 由于triger和表用一个DMSource所以要区分和表的迁移成功标记 */
boolean isTrigerSuccess = false;
又例如
/** 由于triger和表用一个DMSource所以要区分和表的迁移成功标记 */
boolean isTrigerSuccess = false;
再例如
/**
* The Xcoordinate of the component
*
* @see #getLocation()
*/
int x = ;
方法注释
方法注释采用 /** … */描述部分注明方法的功能块标记部分注明方法的参数返回值异常等信息例如
/**
* 设置是否有外码约束
*
* @param conn
* Connection 与数据库的连接
*/
定义注释
规则同域注释
