一、介绍
Javadoc是一种工具,用于解析一组源文件中的声明和文档注释,并生成一组描述类,接口,构造函数,方法和字段的HTML页面。
更详细的请参考:Javadoc使用详情
二、基本使用(windows系统)
撰写文档评论
文档注释的格式:
文档注释使用HTML编写,并且必须在类,字段,构造函数或方法声明之前。它由两部分组成-一个描述,后跟块标签。在该例子中,块标记是 @param, @return,和 @see。
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute {@link URL}. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}
Notes:
将 得到的HTML从运行的Javadoc如下所示
上面的每一行都缩进以与注释下面的代码对齐。
第一行包含开始注释定界符( /**)。
从Javadoc 1.4开始, 前导星号是可选的。
将第一句话写为方法的简短摘要,因为Javadoc自动将其放在方法摘要表(和索引)中。
请注意inline标记 {@link URL},它将转换为指向URL类文档的HTML超链接。此内联标签可在任何可写注释的地方使用,例如在块标签后面的文本中。
如果您在文档注释中有多个段落,请使用
段落标记将各个段落分开 ,如图所示。
如图所示,在描述和标签列表之间插入空白注释行。
以“ @”字符开头的第一行将结束描述。每个文档注释只有一个描述块;您不能在块标记后继续描述。
最后一行包含结尾注释定界符( */)。请注意,与开始注释定界符不同,结尾注释仅包含一个星号。
写在类上面的Javadoc分为三段:
- 概要描述
- 详细描述
- 文档标注
1.概要:
通常用一句或者一段话简要描述该类的作用,以英文句号作为结束。
Class comment 示例:
/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version 1.13, 06/08/06
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}
单行示例:
package org.springframework.util;
/**
* Miscellaneous {@link String} utility methods.
*
*/
public abstract class StringUtils {
多行示例:
package java.lang;
/**
* Class {@code Object} is the root of the class hierarchy.
* Every class has {@code Object} as a superclass. All objects,
* including arrays, implement the methods of this class.
*/
public class Object {}
包装
要记录的软件包名称,例如,用空格分隔java.lang java.lang.reflect java.awt。如果您还想记录子包,请使用该-subpackages选项指定包。
默认情况下,javadoc在当前目录和子目录中查找指定的软件包。使用该-sourcepath选项可以指定要在其中查找软件包的目录列表。
源文件
您要记录的Java源文件的名称,例如,用空格分隔Class.java Object.java Button.java。默认情况下,javadoc在当前目录中查找指定的类。但是,您可以指定类文件的完整路径并使用通配符,例如/home/src/java/awt/Graphics*.java。您还可以指定相对于当前目录的路径。
选项
命令行选项,以空格分隔。
@argfiles
包含javadoc命令选项,软件包名称和源文件名称(以任何顺序排列)的列表的文件名。
源代码注释
可以在源代码中包括文档注释,在任何类,接口,方法,构造函数或字段的声明之前。您也可以为每个软件包创建文档注释,为概述创建另一个注释,尽管它们的语法略有不同。文档注释由其间的字符/*和/结尾的字符组成。每行都允许使用前导星号,并在下一节中进行进一步说明。注释中的文本可以继续多行。
在注释中出现以@开头东东被称之为Javadoc文档标记,是JDK定义好的,如@author、@version、@since、@see、@link、@code、@param、@return、@exception、@throws等。
/ **
*这是简单文档注释的典型格式
*跨两行。
* /
为了节省空间,可以在一行上发表了言论
/ **此注释仅占用一行。* /
1.@link
构造函数和方法标签
下列标记可以出现在构造函数或方法的文档注释中,但@return不能在构造函数中出现的{@inheritDoc}标记和具有限制的标记除外。
Method comment 示例:
/**
* Returns the character at the specified index. An index
* ranges from <code>0</code> to <code>length() - 1</code>
*
* @param index the index of the desired character.
* @return the desired character.
* @exception StringIndexOutOfRangeException
* if the index is not in the range <code>0</code>
* to <code>length()-1</code>
* @see java.lang.Character#charValue()
*/
public char charAt(int index) {
...
}