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