Javadoc注释规范

　　Javadoc虽然是Sun公司为Java文档自动生成设计的，可以从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。（Javadoc is a documentation generator from Sun Microsystems for generating API documentation in HTML format from Java source code. -- 维基百科）但是Javadoc的注释也符合C的注释格式，而且doxyen也支持该种风格的注释，所以简单学习一下。以下的内容来自官方文档，维基百科和一些网上的文档。

　　官方文档：http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html

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

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

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

Overview:

 

 /**

     * @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

    }

Class:

 

 

/**

 * 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 {

   ...

}

Method:

 

 

/**

     * 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) {

       ...

    }

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

Overview Tags
@see @since @author @version {@link} {@linkplain} {@docRoot}

Class/Interface Tags
@see @since @deprecated @serial @author @version {@link} {@linkplain} {@docRoot}

Method/Constructor Tags
@see @since @deprecated @param @return @throws and @exception @serialData {@link} {@linkplain} {@inheritDoc} {@docRoot}

Tag & Parameter	Usage	Applies to	Since
@author name	Describes an author. 描述作者	Class, Interface
@version version	Provides version entry. Max one per Class or Interface. 版本条目，每个类或接口最多有一个	Class, Interface
@since since-text	Describes since when this functionality has existed. 描述这个功能块从何时有的	Class, Interface, Field, Method
@see reference	Provides a link to other element of documentation. 提供链接到其他文档元素的链接	Class, Interface, Field, Method
@param name description	Describes a method parameter. 描述一个参数	Method
@return description	Describes the return value. 描述返回值	Method
@exception classname description @throws classname description	Describes an exception that may be thrown from this method. 描述该方法可能抛出的异常	Method
@deprecated description	Describes an outdated method. 描述一个过期的方法	Method
{@inheritDoc}	Copies the description from the overridden method. 从复写方法出拷贝来得描述	Overriding Method	1.4.0
{@link reference}	Link to other symbol. 连到其他的引用	Class, Interface, Field, Method
{@value}	Return the value of a static field. 返回一个静态作用域的值	Static Field	1.4.0