Unlimited Blade Works

Unaware of loss.Nor aware of gain.

导航

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

posted on 2010-11-10 15:00  飞鸿无月  阅读(12404)  评论(0编辑  收藏  举报