 |
|
Java中javadoc注釋使用規則 |
|
|
在Java中，提供了3種注釋方式：短（單行）注釋、塊（多行）注釋及文檔注釋。單行和多行注釋很容易理解，將注釋符之間的內容當做注釋，在編譯和運行時將這部分內容忽略。下面介紹單行注釋和多行注釋的方法。 （1）單行注釋：單行注釋就是在程序中注釋一行代碼。 注釋規則：在代碼中單起一行注釋， 注釋前好有一行空行，并與其后的代碼具有一樣的縮進層級。如果單行無法完成，則應采用塊注釋。 注釋格式：： // 注釋內容 （2）多行注釋：一次將程序中的多行注釋掉。 注釋規則：注釋若干行，通常用于提供文件、方法、數據結構等的意義與用途的說明，或者算法的描述。一般位于一個文件或者一個方法的前面，起到引導的作用，也可以根據需要放在合適的位置。 注釋格式： /* 來看一個單行注釋和多行注釋的例子。 源文件：MessageComment.java //這是一個單行注釋 在Java中，比較特殊的是javadoc注釋，包含在這部分中的注釋可以通過javadoc命令來自動生成API文檔。通過javadoc工具，可以保證程序代碼和技術文檔的同步。在修改了程序中的注釋后，只需要通過javadoc，就可以方便地生成相應的技術文檔。 我們知道，在軟件開發過程中，文檔編寫的重要性不亞于程序代碼本身。如果代碼與文檔是分離的，那么在每次修改代碼時，都需要修改相應的文檔就會是一件很麻煩的事情。 所以通過javadoc將代碼同文檔“連接”起來。在Java中，還有一種特別的注釋方式：文檔注釋。利用這種注釋，可以從Java源文件中提取這些注釋的內容，來產生HTML格式的API文檔。 文檔注釋的基本格式如下： /** 注意把文檔注釋和多行注釋區分清楚，文檔注釋的開始標記是“/**”，而多行注釋標記的開始標記是“/*”。 由于文檔注釋重要的一個功能就是用它來生成HTML格式的API文檔，因此，很多用于HTML格式化的HTML標記也可以用在文檔注釋中，在從這些注釋中提取注釋生成HTML文件的時候，在生成的HTML文件中，將使用這些HTML標記來格式化HTML文件內容。常用的HTML標記有<b>…</b>、<code>…</code>等。關于這些HTML標記及其他的HTML標記，請讀者參考相關的HTML資料。 和多行注釋不同的另一個地方是，文檔注釋并不是可以放在Java代碼的任何地方，javadoc工具在從Java代碼中提取注釋生成API文檔時，主要從以下幾項內容中提取信息。 ·包。 因此，文檔注釋也應該放到相應的位置中。 1．文檔注釋位置 （1）類注釋。類注釋用于說明整個類的功能、特性等，它應該放在所有的“import”語句之后，在class定義之前。 這個規則也適用于接口（interface）注釋。 （2）方法注釋。方法注釋用來說明方法的定義，比如，方法的參數、返回值及說明方法的作用等。方法注釋應該放在它所描述的方法定義前面。 （3）屬性注釋。默認情況下，javadoc只對公有（public）屬性和受保護屬性（protected）產生文檔——通常是靜態常量。 （4）包注釋。類、方法、屬性的注釋都直接放到Java的源文件中，而對于包的注釋，無法放到Java文件中去，只能通過在包對應的目錄中添加一個package.html的文件來達到這個目的。當生成HTML文件時，package.html文件的<BODY>和</BODY>部分的內容將會被提取出來當做包的說明。關于包注釋，后面還會有更進一步的解釋。 （5）概要注釋。除了包注釋外，還有一種類型的文檔無法從Java源文件中提取，就是對所有類文件提供概要說明的文件。同樣的，也可以為這類注釋單獨新建一個HTML文件，這個文件的名字為“overview.html”，它的<BODY>和</BODY>標記之間的內容都會被提取。 2．javadoc標記 在javadoc注釋中，常用@來表示一個javadoc標記，常用的javadoc標記如下： ·@author：作者。 需要注意這些標記的使用是有位置限制的。其中可以出現在類或者接口文檔注釋中的標記有：@see、@deprecated、@author、@version等。可以出現在方法或者構造器文檔注釋中的標記有：@see、@deprecated、@param、@return、@throws、@exception等。可以出現在屬性文檔注釋中的有：@see、@deprecated等。 3．javadoc命令語法 javadoc的命令行語法如下： javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ] 參數可以按照任意順序排列。下面對這些參數作一些說明。 （1）packagenames 包列表：這個選項可以是一系列的包名（用空格隔開），例如，java.lang java.lang.reflect java.awt。因為javadoc不遞歸作用于子包，不允許對包名使用通配符；所以必須顯式地列出希望建立文檔的每一個包。 （2）sourcefiles 源文件列表。這個選項可以是一系列的源文件名（用空格隔開），可以使用通配符。javadoc允許4種源文件：類源代碼文件、包描述文件、總體概述文件、其他雜文件。 ·類源代碼文件：類或者接口的源代碼文件。 ·包描述文件：每一個包都可以有自己的包描述文件。包描述文件的名稱必須是 “package.html”，與包的.java文件放置在一起。包描述文件的內容通常是使用HTML標記寫的文檔。javadoc執行時將自動尋找包描述文件。如果找到，javadoc將首先對描述文件中<body></body>之間的內容進行處理，然后把處理結果放到該包的Package Summary頁面中，后把包描述文件的第一句（緊靠<body>）放到輸出的Overview Summary頁面中，并在語句前面加上該包的包名。 總體概述文件：javadoc可以創建一個總體概述文件描述整個應用或者所有包。總體概述文件可以被任意命名，也可以放置到任意位置。-overview選項可以指示總體概述文件的路徑和名稱。總體概述文件的內容是使用HTML標記寫的文檔。javadoc在執行的時候，如果發現-overview選項，那么它將首先對文件中<body></body>之間的內容進行處理；然后把處理后的結果放到輸出的Overview Summary 頁面的底部；后把總體概述文件中的第一句放到輸出的Overview Summary頁面的頂部。 其他雜文件：這些文件通常是指與javadoc輸出的HTML文件相關的一些圖片文件、Java源代碼文件（.java）、Java程序（.class）、Java小程序（Applets）、HTML文件。這些文件必須放在doc-files目錄中。每一個包都可以有自己的doc-files目錄。例如，你希望在java.awt.Button的HTML文檔中使用一幅按鈕的圖片（Button.gif）。首先，必須把圖片文件放到java\awt\doc-files\中；然后在Button.java文件中加入以下注釋： /** files 包含文件。為了簡化javadoc命令，可以把需要建立文檔的文件名和包名放在一個或多個文本文件中。例如，為了簡化以下命令： javadoc -d apidoc com.oristand.college com.oristand.school 可以建立一個名稱為mypackage.txt的文件，其內容如下： com.oristand.college 然后執行以下命令即可： javadoc -d apidoc @mypackage.txt ·options 命令行選項。 ① public 只顯示公共類及成員。 -classpath classpathlist 指定javadoc查找“引用類”的路徑。引用類是指帶文檔的類加上它們引用的任何類。javadoc將搜索指定路徑的所有子目錄，classpathlist可以包含多個路徑（使用“;”隔開）。 一切就緒后，就可以使用JDK中的“javadoc”工具來生成相關的API文檔了。 熱點鏈接：
1、Java源文件結構詳解 |