javadoc的命令行语法(二)

2014-11-24 08:27:05 · 作者: · 浏览: 1

◇ - group groupheading packagepatten;packagepatten;… 在总体概述页面中按照命令的指定方式分隔各个包。例如执行下面命令:
javadoc -group "Core Packages" "java.lang*:java.util"
-group "Extension Packages" "javax.*"
java.lang java.lang.reflect java.util javax.servlet java.new
在页面中将有如下结果:
Core Packages
java.lang
java.lang.reflect
java.util
Extension Packages
javax.servlet
Other Packages
java.new
◇ - noindex 不输出索引文件。
◇ - help 在文件的导航条中忽略help链接。
◇ - helpfile pathfilename 指定导航条中的help链接所指向的帮助文件。忽略该选项,javadoc将生成缺省的帮助文件。
◇ -stylesheetfile pathfilename 指定javadoc的HTML样式表文件的路径。忽略该选项,javadoc将自动产生一个样式表文件stylesheet.css。
JavaDoc文档标记
javadoc注释以""结束,里面可以包含普通文本、HTML标记和javadoc标记。javadoc只处理源文件中在类/接口定义、方法、域、构造器之前的注释,忽略位于其他地方的注释。举例如下:

public class myHelloworld
{

static String SDisplay;

public static void main(String args[])
{
SDisplay = "Hello World " ;
System.out.println( SDisplay );
}
}

使用下面命令:
javadoc -private -d doc -author -version myHelloworld.java
即可以生成漂亮的关于myHelloworld.java的API文档了。
上面例子中以@开头的标记就是javadoc标记。在Java程序中正确使用javadoc标记是一个良好的注释习惯,将非常有助于javadoc自动从源代码文件生成完整的格式化API文档。下面就对各种标记进行详细说明。
◇ @author name-text 指定生成文档中的"作者"项,从JDK/SDK 1.0开始引入。name-text可以指定多个名字(使用","隔开)。文档注释可以包含多个类。
{@docroot} 代表产生文档的根路径,从JDK/SDK 1.3开始引入。用法举例如下

假定生成文档的根目录是doc,上面注释所在的文件最后生成的文件是docutilityutl.html,那么"copyright"的链接会指向..copyright.html。
◇ @deprecated deprecated-text 添加注释,表明不推荐使用该API。
◇ @exception class-name description @throw的同义标记,从JDK/SDK 1.0开始引入。
{@link package.class#member label} 插入指向package.class#member的内嵌链接,从JDK/SDK 1.2开始引入。举例说明,假定注释中有如下文档:

那么javadoc最终生成的HTML页面中将有如下内容
Use the getComponentAt method.
◇ @param parameter-name description 描述参数,从JDK/SDK 1.0开始引入。
◇ @return description 描述返回值,从JDK/SDK 1.0开始引入。
◇ @see reference 添加"参见"标题,其中有指向reference的链接或者文本项,从JDK/SDK 1.0开始引入。@see标记有三种形式,下面分别说明:
(1)、@see "string" 为"string"添加文本项,不产生链接。
(2)、@see Label 使用HTML标记产生链接
(3)、@see package.class#member Label 使用Java语言的名字package.class #member产生链接。
◇ @serial field-description 用于缺省可序列化域的注释,从JDK/SDK 1.2开始引入。
◇ @serialField field-name field-type field-description 建立Serializable类的serialPersistentFields成员的ObjectStreamField组件的文档,从JDK/SDK 1.2开始引入。
◇ @serialData data-description data-description建立数据序列和类型的文档,从JDK/SDK 1.2开始引入。
◇ @since since-text 利用since-text内容为文档增加"since"标题,从JDK/SDK 1.1开始引入。
◇ @throws class-name description 与@exception同义。用class-name和description为输出文档添加"抛出"标题,从JDK/SDK 1.2开始引入。
◇ @version version-text 添加"版权"标题,从JDK/SDK 1.0开始引入。
上面介绍了标准doclet提供的所有标记。不过,需要注意这些标记的使用是有位置限制的。其中可以出现在类或者接口文档注释中的标记有:@see、 {@link}、@since、@deprecated、@author、@version。可以出现在方法或者构造器文档注释中的标记有:@see、 {@link}、@since、@deprecated、@param、@return、@throws、@exception、 @serialData。可以出现在域文档注释中的有:@see、{@link}、@since、@desprecated、@serial、 @serialField。
除了javadoc自身提供的标准标记以外,我们可以定制自己的标记吗?当然可以。只需要对javadoc标准的doclet程序进行扩充即可。实际上,利用javadoc提供的doclet API,不仅可以扩充doclet标记,甚至还可以改变javadoc的整个输出。为了满足需要,你可以使javadoc输出普通文本、XML文件等。由于扩充doclet涉及到Java编程,本文不再做深入介绍。
总之,javadoc提供了完整规范的API文档功能。在软件项目管理中,合理地使用javadoc不仅可以减少开发时的文档工作量,提高效率;而且还非常有利于将来软件的修改和维护。
JavaDoc 书写规范:
1、 File Header Comments : 每个文件都应该加上文件头标记,包括文件名、修改历史、版权信息和附加信息。例如:

2、class description:类信息,概括的描述类的功能和实现。

3、Variable Description:描述变量的意义和取值含义。

4、Method Description:标明每个方法的输入、输出参数和返回值类型,说明特殊变量取值的含义。相关类文档链接。


5、Association Descri