Java 文檔注釋

bladefury 發(fā)布于2019-08-14 15:11 / 666人閱讀

摘要：概述只有種注釋方式。單行注釋塊注釋說明注釋，等說明注釋允許你在程序中嵌入關(guān)于程序的信息。每一個(gè)標(biāo)簽必須在一個(gè)新行的開始。多個(gè)相同類型的標(biāo)簽應(yīng)該放成一組。類描述輸出工具將你程序的源代碼作為輸入，輸出一些包含你程序注釋的文件。參考資料文檔注釋

概述

Java只有3種注釋方式。

//,單行注釋

/* */,塊注釋

說明注釋，@author,@version等

說明注釋允許你在程序中嵌入關(guān)于程序的信息。你可以使用javadoc工具軟件來生成信息，并輸出到HTML文件中。

Javadoc 標(biāo)簽

javadoc工具軟件識(shí)別以下標(biāo)簽

標(biāo)簽	描述
@author	標(biāo)示一個(gè)類的作者
@deprecated	標(biāo)識(shí)一個(gè)過期的類或成員
{@docRoot}	指明當(dāng)前文檔跟目錄的路徑
@exception	指明一個(gè)類拋出的異常
@throws	和@exception一樣
{@inheritDoc}	從直接父類繼承的注釋
{@link}	插入一個(gè)到另一個(gè)主題的鏈接
{@linkplain}	插入一個(gè)到另一個(gè)主題的鏈接，但該鏈接顯示純文本字體
@param	說明一個(gè)方法的參數(shù)
@return	說明返回值類型
@see	指定一個(gè)到另一個(gè)主題的鏈接
@serial	說明一個(gè)序列化屬性
@serialData	說明通過 writeObject() 和 writeExternal() 方法寫的數(shù)據(jù)
@serialField	說明一個(gè)ObjectStreamField組件
@since	標(biāo)記當(dāng)引入一個(gè)特定的變化時(shí)
{@value}	顯示常亮的值，必須是static屬性
@version	指定類的版本號(hào)

文檔注釋

在開始的/**之后，第一行或幾行是關(guān)于類、變量和方法的主要描述。

之后，你可以包一個(gè)或多個(gè)各種各樣的@標(biāo)簽。每一個(gè)@標(biāo)簽必須在一個(gè)新行的開始。

多個(gè)相同類型的標(biāo)簽應(yīng)該放成一組。例如，如果你有三個(gè)@see標(biāo)簽，可以將它們一個(gè)接一個(gè)的放在一起。

/** 
* 類描述
* @author panda
* @version 1.2
*/
...

Javadoc 輸出

Javadoc 工具將你Java程序的源代碼作為輸入，輸出一些包含你程序注釋的HTML文件。

每一個(gè)類的信息將在獨(dú)自的HTML文件里。Javadoc也可以輸出繼承的樹形結(jié)構(gòu)和索引。

由于Javadoc的實(shí)現(xiàn)不同，工作也可能不同，你需要檢查你的Java開發(fā)系統(tǒng)的版本等細(xì)節(jié)，選擇合適的Javadoc版本。

實(shí)例

package com.coder4j.jse.javadoc;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;

/**
 * 輸入一個(gè)數(shù)，輸出其平方數(shù)。
 * 
 * @author panda
 * @version 1.2
 */
public class SquareNum {
    
    /**
     * 輸出平方值。
     * 
     * @param num
     *            待求平方數(shù)
     * @return 平方值
     */
    public double square(double num) {
        return num * num;
    }

    /**
     * 用戶輸入一個(gè)數(shù)
     * 
     * @return 返回用戶輸入的數(shù)
     * @exception IOException
     *                可能拋出的異常
     * @see IOException
     */
    public double getNumber() throws IOException {
        InputStreamReader isr = new InputStreamReader(System.in);
        BufferedReader inData = new BufferedReader(isr);
        String str;
        str = inData.readLine();
        return (new Double(str)).doubleValue();
    }

    /**
     * 入口主函數(shù)
     * 
     * @param args
     *            Unused.
     * @return Nothing.
     * @exception IOException
     *                On input error.
     * @see IOException
     */
    public static void main(String args[]) throws IOException {
        SquareNum ob = new SquareNum();
        double val;
        System.out.println("請(qǐng)輸入一個(gè)數(shù): ");
        val = ob.getNumber();
        val = ob.square(val);
        System.out.println("平方值是: " + val);
    }
}

我在eclipse里寫了這個(gè)類，右鍵export，選擇Java/javadoc 然后按提示確認(rèn)，控制臺(tái)輸出：

正在加載程序包c(diǎn)om.coder4j.jse.javadoc的源文件...
正在構(gòu)造 Javadoc 信息...
標(biāo)準(zhǔn) Doclet 版本 1.7.0_75
正在構(gòu)建所有程序包和類的樹...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/SquareNum.html...
/Users/panda/Documents/lunaspace/code4j/src/com/coder4j/jse/javadoc/SquareNum.java:52: 警告 - 不能在返回類型為空的方法中使用 @return 標(biāo)記。
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/package-frame.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/package-summary.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/package-tree.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/constant-values.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/class-use/SquareNum.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/com/coder4j/jse/javadoc/package-use.html...
正在構(gòu)建所有程序包和類的索引...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/overview-tree.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/index-files/index-1.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/index-files/index-2.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/index-files/index-3.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/index-files/index-4.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/deprecated-list.html...
正在構(gòu)建所有類的索引...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/allclasses-frame.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/allclasses-noframe.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/index.html...
正在生成/Users/panda/Documents/lunaspace/code4j/doc/help-doc.html...
1 個(gè)警告

默認(rèn)在當(dāng)前項(xiàng)目下新增doc目錄

doc/
|--com
|--index-files
|--resources
|--allclasses-frame.html
|--allclasses-noframe.html
|--constant-values.html
|--deprecated-list.html
|--help-doc.html
|--index.html
|--overview-tree.html
|--package-list
|--stylesheet.css

可以直接訪問index.html,你會(huì)看到類似這樣的頁面。

不同的Javadoc版本可能稍有不同喲。

參考資料

Java 文檔注釋