Javadoc
1、定义
javadoc是Sun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套 的API帮助文档。也就是说,只要在编写程序时以一套特定的标签作注释,在程序编写完成后,通过Javadoc就可以同时形成程序的开发文档了。
javadoc命令是用来生成自己API文档的,使用方式:使用命令行在目标文件所在目录输入javadoc +文件名.java。
2、ava 文档注释
Java 支持三种注释方式。前两种分别是 // 和 /* /,第三种被称作说明注释,它以 /* 开始,以 */结束。这说明注释允许你在程序中嵌入关于程序的信息,所以可以使用 javadoc 工具软件来生成信息,并输出使用说明注释,让你更加方便的记录你的程序信息。
一、 Java文档
// 注释一行
/ * */ 注释若干行
/** ……*/ 注释若干行,写入Javadoc文档
二、文档格式
写在类上的文档标注一般分为三段:
第一段:概要描述,通常用一句话或者一段话简要描述该类的作用,以英文句号结束;
第二段:详细描述,通常用一段或者多段话来详细描述该类的作用,一般每段话都以英文句号作为结束;
第三段:文档标注,用于标注作者,创建时间,参阅类等信息;
生成文档是HTML格式。
换行<br>
分段<p>(写在段前))
方法详细描述上经常使用html标签来,通常都以p标签开始,而且p标签通常都是单标签,不使用结束标签,其中使用最多的就是p标签和pre标签,ul标签, i标签。
pre元素可定义预格式化的文本。被包围在pre元素中的文本通常会保留空格和换行符。而文本也会呈现为等宽字体,pre标签的一个常见应用就是用来表示计算机的源代码。
一般p经常结合pre使用,或者pre结合@code共同使用(推荐@code方式)
一般经常使用pre来举例如何使用方法
注意:pre>标签中如果有小于号、大于号、例如泛型 在生产javadoc时会报错
Eg:
/**
* show 方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true 表示显示,false 表示隐藏
* @return 没有返回值
*/
public void show(boolean b) {
frame.show(b);
}
3、javadoc标签
4、Javadoc命令
一、Javadoc命令是用来生成自己的API文档,使用方式:
javadoc 源文件名.java
javadoc -d 文档存放目录 源文件名.java
通过IDEA生成Javadoc : Tools -> Generate JavaDoc
二、命令格式编辑
Javadoc命令格式如下:
javadoc [选项] [软件包名称] [源文件]
其中选项有:
-overview <文件> 读取 HTML 文件的概述文档
-public 仅显示公共类和成员
-protected 显示受保护/公共类和成员(默认)
-package 显示软件包/受保护/公共类和成员
-private 显示所有类和成员
-help 显示命令行选项并退出
-doclet <类> 通过替代 doclet 生成输出
-docletpath <路径> 指定查找 doclet 类文件的位置
-sourcepath <路径列表> 指定查找源文件的位置
-classpath <路径列表> 指定查找用户类文件的位置
-exclude <软件包列表> 指定要排除的软件包的列表
-subpackages <子软件包列表> 指定要递归装入的子软件包
-breakiterator 使用 BreakIterator 计算第 1 句
-bootclasspath <路径列表> 覆盖引导类加载器所装入的类文件的位置
-source <版本> 提供与指定版本的源兼容性
-extdirs <目录列表> 覆盖安装的扩展目录的位置
-verbose 输出有关 Javadoc 正在执行的操作的消息
-locale <名称> 要使用的语言环境,例如 en_US 或 en_US_WIN
-encoding <名称> 源文件编码名称
-quiet 不显示状态消息
-J<标志> 直接将 <标志> 传递给运行时系统
5、javadoc 输出什么
avadoc 工具将你 Java 程序的源代码作为输入,输出一些包含你程序注释的HTML文件。
每一个类的信息将在独自的HTML文件里。javadoc 也可以输出继承的树形结构和索引。
由于 javadoc 的实现不同,工作也可能不同,你需要检查你的 Java 开发系统的版本等细节,选择合适的 Javadoc 版本。
下面以 eclipse 为例
首先是在文件头部添加:
注:在注释中出现以@开头东东被称之为Javadoc文档标记,是JDK定义好的,如@author、@version、@since、@see、
@link 、@code、@param、@return、@exception、@throws等。
/*
* <p>项目名称: ${project_name} </p>
* <p>文件名称: ${file_name} </p>
* <p>描述: [类型描述] </p>
* <p>创建时间: ${date} </p>
* <p>公司信息: ************公司 *********部</p>
* @author <a href="mail to: *******@******.com" rel="nofollow">作者</a>
* @version v1.0
* @update [序号][日期YYYY-MM-DD] [更改人姓名][变更描述]
*/
方法:
/**
* @Title:${enclosing_method}
* @Description: [功能描述]
* @Param: ${tags}
* @Return: ${return_type}
* @author <a href="mail to: *******@******.com" rel="nofollow">作者</a>
* @CreateDate: ${date} ${time}</p>
* @update: [序号][日期YYYY-MM-DD] [更改人姓名][变更描述]
*/
getter 和 setter
/**
* 获取 ${bare_field_name}
*/
/**
* 设置 ${bare_field_name}
* (${param})${field}
*/