自己总结的Javadoc编写规范.doc

JavaDoc编写示例说明1.在class的编写中,为了以后让自己或其它程序员能够熟练使用本类,而编写的文档信息.2. 文档说明文件默认在 src/doc文件夹,文件名是 index.html,由myEclipse输出.3.方法为myEclipse-file-export-javadoc-选择要输出的类文件,再选择protected(以便继承描述).其它默认. 4.在myEclipse里可以设置自动加载注释,myEclipse-windows-perferences-java-codeStyle-codeTemplates-comments下.1.Files 文件头2.Types 类定义3.Fields 字段摘要(成员变量)4.Constructors 构造函数5.Methods 方法6.Getters,7.Setters5.在myEclipse里输入/* 回车,就以快速弹出自定义的文档范例6.输入 # ALT+/ 都可以快速弹出示例. myEclipse-windows-perferences-java-codeEditor-Templates以下是class中件里的java文档示例一.Files 文件头(写在文件最前方)myEclipse定义/* * Description: * * Copyright (c) 2013,ChongQing H3C Technologies Co.,Ltd.All rights reserved. * / * Author:杨易 QQ:804726030 Email: * Since:$date $time by:杨易 */示例/* * Description:数据库连接,操作,表信息查询 需要sqljdbc4.jar驱动程序 * * Copyright (c) 2013,ChongQing H3C Technologies Co.,Ltd.All rights reserved. * / * Author:杨易 QQ:804726030 Email: * Since:2013-4-18 下午12:08:41 by:杨易 */2.Types 类体(写在类定义的前方)定义/* * 功能简单说明. * 例1: * 例2: * * see 相关类/方法2 * version version 2.1 * since $date $time by:杨易 */示例:/* * 数据库连接,操作,表信息查询 * 需要 sqljdbc4.jar驱动程序. * 例1: ConnectionDatabase(,1433,yydb,sa,097040); * 例2: ConnectionDatabase(databaseName) ip地址,端口号,用户名,密码都可以默认; * 对数据库进行连接 * 可以得到该数据库表格信息(表格名称,字段信息,字段类型) * 可以对数据库进行DML,DQL,DDL操作 * * see ConnectionDatabase#getTableNames() getTableNames 得到当前数据库所有表格名称 * see ConnectionDatabase#getTableFiledNames() getTableFiledNames 得到字段名称 * see ConnectionDatabase#getTableFiledTypes() getTableFiledTypes 得到字段类型 * see ConnectionDatabase#DML(String) DML 数据库管理语言 insert,update,delete * see ConnectionDatabase#DQL(String) DQL 数据库查询语言 query * see ConnectionDatabase#DQL(String, String) DQL 数据库查询语言(注入式) query * see ConnectionDatabase#DDL(String) DDL 数据库定义语言 create,drop,alter * since : 2013-4-18 下午3:03:41 by 杨易 * */3.Fields 字段摘要(成员属性)/*男性，值为value*/public static final int MALE = 1;4.Constructors 构造方法摘要模板/* * 功能简单说明. * 例: * * param 参数1参数说明 * exception NullPointerException 异常说明 * see 相关类/方法2 */完整示例/* * 创建一个数据库连接 需要指定服务器ip,端口,数据库名称,用户名和密码 适用于sqlserver身份验证登陆远程数据库. * * * 例ConnectionDatabase(localhost,1433,northwind,sa,097040) * * param serverName * 数据库ip * param portNumber * 数据库端口 * param databaseName * 数据库名称 * param users * sqlserver身份验证的用户名 * param password * sqlserver身份验证的的密码 * exception Exception * 数据库不存在,sqlserver用户名密码错误,出现登陆异常 */5.Methods 方法摘要范本/* * 功能简单说明. * 例: * * param 参数1参数说明 * return 返回类型说明 * exception NullPointerException 异常说明 * see 相关类/方法1*/实例:/* * 数据库查询语言 DQL 注入式. * * * 例: String paras = U, employees; * cd.DQL(select name from sysobjects where XType=? and name=? ,paras) * * ps = ct.prepareStatement(sqlStr); * ps.setString(1) * ps.setString(2) * ps.executeQuery(); * * see ConnectionDatabase#DQL(String) DQL 数据库查询语言 select * param sqlStr * sql查询语句 select * param paras * 一个注入的参数数组 String paras = U, employees; * return resultSet 一个结果集rs,如果没有结果返回为null * exception Exception * sql查询语句错误 */6.Setters 由sources-getters/setters/* * 功能简介: * 例: * * param $param the $bare_field_name to set * exception/throws 异常类型异常说明2 */7.Getters 由sources-getters/setters/* * 功能简介: * 例: * * return the $bare_field_name * exception/throws 异常类型异常说明2 */各种参数使用方法 标记类型、名称、专用注释。 1.标记类型 由javadoc自动识别 2.名称 由javadoc自动识别并加- 3.名称说明 名称的说明标记 用于 作用 author 对类的说明 标明开发该类模块的作者 version 对类的说明 标明该类模块的版本 see 对类、属性、方法的说明参考转向，也就是相关主题 param 对方法的说明 对方法中某参数的说明 return 对方法的说明 对方法返回值的说明 exception对方法的说明 对方法可能抛出的异常进行说明 deprecated表示当前方法已经不推荐使用，已由新方法取代。1.see 的使用，可输入see alt+/ 选择类名. # 选择成员方法和属性see主要是转向文档中相关的主题，如果有此主题则有超导链接，它 的句法有三种：see 类名 see #方法名或属性名see 类名#方法名或属性名2 .使用 param、return 和 exception 说明方法这三个标记都是只用于方法的。param 描述方法的参数，return 描述方法的返回值，exception 描述方法可能抛出的异常。它们的句法如下： param 参数名 参数说明 return 返回值说明 exception 异常类名 说明每一个 param 只能描述方法的一个参数，所以，如果方法需要多个参数，就需要多次使用 param 来描述。一个方法中只能用一个 return，如果文档说明中列了多个 return，则 javadoc 编译时会发出警告，且只有第一个 return 在生成的文档中有效。* param b excrescent parame