javaDoc 注释规范

Javadoc虽然是Sun公司为Java文档自动生成设计的，可以从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。但是Javadoc的注释也符合C的注释格式，而且doxyen也支持该种风格的注释。

官方文档：http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html

维基百科：https://en.wikipedia.org/wiki/Javadoc

Javadoc 的注释结构和 C 类似。都以/* 注释 */这种结构。

Javadoc 的内容很多，我只是先学习一下 Overview注释，类注释 和 方法注释，其他的以后再学。先贴出几段 Java 的示例代码。

概述:

/**
 * @author      Firstname Lastname <address @ example.com>
 * @version     2010.0331  (E.g. ISO 8601 YYYY.MMDD)
 * @since       1.6        (The Java version used)
 */
public class Test {
    // class body
}

类:

/**
 * A class representing a window on the screen.
 * For example:
 * <pre>
 *    Window win = new Window(parent);
 *    win.show();
 * </pre>
 *
 * @author  Sami Shaio
 * @version %I%, %G%
 * @see     java.awt.BaseWindow
 * @see     java.awt.Button
 */
class Window extends BaseWindow {
    ...
}

字段/变量

/**
 * The X-coordinate of the component.
 *
 * @see #getLocation()
 */
int x = 1263732;

/**
 * The horizontal distances of point.
 */
public int x;

方法:

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

/**
 * Validates a chess move.
 *
 * @param theFromFile file from which a piece is being moved
 * @param theFromRank rank from which a piece is being moved
 * @param theToFile   file to which a piece is being moved
 * @param theToRank   rank to which a piece is being moved
 * @return            true if the move is valid, otherwise false
 */
boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
    // ...body
}

/**
 * Moves a chess piece.
 *
 * @see java.math.RoundingMode
 */
void doMove(int theFromFile, int theFromRank, int theToFile, int theToRank)  {
    // ...body
}

其实这些注释形式都差不多，主要是 tag 不同下面介绍一下 tag 及含义。