javadoc工具详解

在编写完成java程序中的文档注释后,可以使用javadoc工具提取程序中的文档注释来生成API文档

文档注释示例

javadoc工具详解_第1张图片

javadoc命令可对源文件、包生成API文档,java源文件可以支持通配符,例如

*.java

代表当前路径下所有的java源文件。
javadoc的常用选项有如下几个:

-d < directory > :该选项指定一个路径,用于将生成的API文档放到指定目录下。
-windowtitle < text > : 该选项指定一个字符串,用于设置API文档的浏览器窗口标题。
-doctitle < html-code > : 该选项指定一个HTML格式的文本,用于指定概述页面的标题。(只对有处于多个包下的源文件来生成API文档时,才有概述页面)
-header < html-code > : 该选项指定一个HTML格式的文本,包含每个页面的页眉。

此外:可通过命令行窗口执行 javadoc -help 来查看 javadoc命令的所有选项

示例:
javadoc命令示例

如果希望 javadoc 工具生成更详细的文档信息,例如方法参数、方法返回值等详细的说明信息,则可以利用javadoc标记。常用的javadoc标记如下:

javadoc工具详解_第2张图片

注:
可以出现在类或者接口文档注释中的有: @see、@deprecated、@author、@version 等;
可以出现在方法或者构造器文档注释中的有: @see、@deprecated、@param、@return、@throws和@exception ;
可以出现在成员变量的文档注释有: @see和@deprecated 等;

示例:
这里写图片描述

API 文档中的包注释不是放在java源文件中的,必须另外指定,通常通过一个标准的HTML文件来提供包注释,这个文件被称为包描述文件。包描述文件的文件名通常是 package.html ,并与该包下所有的java源文件放在一起,javadoc工具会自动寻找对应的包描述文件,并提取该包描述文件中的 < body/ > 元素里的内容,作为该包的描述信息。

示例:
javadoc工具详解_第3张图片

如需要设置包描述信息,则需要将java源文件按包结构来组织存放。实际上,当编写java源文件时,通常总会按包结构来组织存放java源文件,这样更有利于项目的管理;

以上就可以生成非常专业的API文档了,和系统提供的API文档基本类似。

你可能感兴趣的:(项目管理,API文档,javadoc工具,javadoc)