Javadoc基本使用

一、介绍

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. 概要描述
2. 详细描述
3. 文档标注

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) {
       ...
    }