我们在开发JAVA程序中, 可以使用Javadoc来进行程序文档的整理, 当程序编写完成, 利用Java自带的JavaDoc工具就可以生成规范的API说明手册. 下面是我自己整理的一些语法: 书写格式: /** <- 这里一定要用两个星号, 否则会被认为是普通注释的 * ........ */ public int getCount() { ....... Javadoc只能为public,protected两种权限的类成员进行处理注释文档。当然也可以使用-private参数强制进行处理, 我们可以在注释中嵌入HTML个标记来丰富最后文档的显示, 因为Javadoc最后生成的文档就是HTML.
/** * 一些参数列表 * * @see 类名 * @see 完整类名 * @see 完整类名#方法 * * @param 参数名 说明 * @return 说明 * @exception 完整类名 说明 * @deprecated * * @version 版本信息 * @author 作者名 */ 说明: @see : 就是文档中的 参见xx 的条目, 其实就是超链接.
一般来说, 文档有三种类型: 类注释, 变量注释, 方法注释, 这三中类型的注释除了都可以包含 @see 参数外, 其它所包含的参数是不同的. 1. 类注释 类注释是写在类前面的, 用来说明类的一些情况, 可以包涵 @version,@author参数, 但Javadoc缺省情况下不处理, 也就是说不在最后文档中出现的, 为了使用这些信息, 我们可以加入参数 -version和 -author来强制输出到最后的文档中. 2. 变量注释 变量注释写在变量前面, 只能包含 @see 参数 3. 方法注释 方法注释可以包括 @param : 参数名是指参数列表内的标识符, 说明就是一些解释性质的文字, 可以多行. @return : 返回值的说明, 可以多行 @exception : 完整类名应该明确指定一个违例类的名字,它是在其它某个地方定义好的。而说明则阐述为什么这种特殊类型的违例会在方法调用中出现。说明可以多行 @deprecated : 指出一些旧功能已由改进过的新功能取代。该标记的作用是建议用户不必再使用一种特定的功能,因为未来改版时可能摒弃这一功能。若将一个方法标记为@deprecated,则使用该方法时会收到编译器的警告。
(iwgh)
|