java doc书写_Javadoc 书写格式和命令

AVADOC语法

我们在开发JAVA程序中, 可以使用Javadoc来进行程序文档的整理, 当程序编写完成, 利用Java自带的JavaDoc工具就可以生成规范的API说明手册. 下面是我自己整理的一些语法:

书写格式:

public int getCount() { .......

Javadoc只能为public,protected两种权限的类成员进行处理注释文档。当然也可以使用-private参数强制进行处理, 我们可以在注释中嵌入HTML个标记来丰富最后文档的显示, 因为Javadoc最后生成的文档就是HTML.

说明:

@see : 就是文档中的 参见xx 的条目, 其实就是超链接.

一般来说, 文档有三种类型: 类注释, 变量注释, 方法注释, 这三中类型的注释除了都可以包含 @see 参数外, 其它所包含的参数是不同的.

1. 类注释

类注释是写在类前面的, 用来说明类的一些情况, 可以包涵 @version,@author参数, 但Javadoc缺省情况下不处理, 也就是说不在最后文档中出现的, 为了使用这些信息, 我们可以加入参数 -version和 -author来强制输出到最后的文档中.

2. 变量注释

变量注释写在变量前面, 只能包含 @see 参数

3. 方法注释

方法注释可以包括

@param : 参数名是指参数列表内的标识符, 说明就是一些解释性质的文字, 可以多行.

@return : 返回值的说明, 可以多行

@exception : 完整类名应该明确指定一个违例类的名字，它是在其它某个地方定义好的。而说明则阐述为什么这种特殊类型的违例会在方法调用中出现。说明可以多行

@deprecated : 指出一些旧功能已由改进过的新功能取代。该标记的作用是建议用户不必再使用一种特定的功能，因为未来改版时可能摒弃这一功能。若将一个方法标记为@deprecated，则使用该方法时会收到编译器的警告。

javadoc的命令行语法如下：

javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]

参数可以按照任意顺序排列。下面分别就这些参数和相关的一些内容进行说明：

? Packagenames 包列表。这个选项可以是一系列的包名(用空格隔开)，例如java.lang java.lang.reflect java.awt。不过，因为javadoc不递归作用于子包，不允许对包名使用通配符；所以你必须显示地列出希望建立文档的每一个包。

? Sourcefiles 源文件列表。这个选项可以是一系列的源文件名(用空格隔开)，可以使用通配符。javadoc允许四种源文件：类源代码文件、包描述文件、总体概述文件、其他杂文件。

◇ 类源代码文件：类或者接口的源代码文件。

◇ 包描述文件：每一个包都可以有自己的包描述文件。包描述文件的名称必须是"package.html"，与包的.java文件放置在一起。包描述文件的内容通常是使用HTML标记写的文档。javadoc执行时将自动寻找包描述文件。如果找到，javadoc将首先对描述文件中

之间的内容进行处理，然后把处理结果放到该包的Package Summary页面中，最后把包描述文件的第一句(紧靠)放到输出的Overview summary页面中，并在语句前面加上该包的包名。

◇ 总体概述文件：javadoc可以创建一个总体概述文件描述整个应用或者所有包。总体概述文件可以被任意命名，也可以放置到任意位置。-overview选项可以指示总体概述文件的路径和名称。总体概述文件的内容是使用HT