 |
|
Java中javadoc注釋使用規則 |
|
|
在(zai)(zai)Java中，提(ti)供了3種注(zhu)(zhu)釋(shi)(shi)方(fang)式：短(duan)（單行(xing)）注(zhu)(zhu)釋(shi)(shi)、塊（多(duo)行(xing)）注(zhu)(zhu)釋(shi)(shi)及文(wen)檔注(zhu)(zhu)釋(shi)(shi)。單行(xing)和多(duo)行(xing)注(zhu)(zhu)釋(shi)(shi)很容(rong)(rong)易理解，將注(zhu)(zhu)釋(shi)(shi)符之間的內(nei)容(rong)(rong)當(dang)做(zuo)注(zhu)(zhu)釋(shi)(shi)，在(zai)(zai)編譯和運行(xing)時將這部分內(nei)容(rong)(rong)忽略。下面介紹單行(xing)注(zhu)(zhu)釋(shi)(shi)和多(duo)行(xing)注(zhu)(zhu)釋(shi)(shi)的方(fang)法。 （1）單(dan)行注釋：單(dan)行注釋就是(shi)在程序中注釋一(yi)行代碼。 注釋(shi)規則：在代碼中單起一(yi)行(xing)注釋(shi)， 注釋(shi)前(qian)好有一(yi)行(xing)空行(xing)，并與其后的(de)代碼具有一(yi)樣的(de)縮進(jin)層級。如果單行(xing)無(wu)法完成，則應采用塊注釋(shi)。 注釋(shi)格式：： // 注釋(shi)內容 （2）多(duo)(duo)行注釋：一次將程序中的(de)多(duo)(duo)行注釋掉。 注釋(shi)規則：注釋(shi)若干行，通常(chang)用(yong)于提(ti)供文(wen)件、方法(fa)、數據結構等的(de)(de)意義與用(yong)途的(de)(de)說明(ming)，或(huo)者(zhe)算法(fa)的(de)(de)描述。一(yi)(yi)般位于一(yi)(yi)個文(wen)件或(huo)者(zhe)一(yi)(yi)個方法(fa)的(de)(de)前(qian)面，起到引導(dao)的(de)(de)作用(yong)，也可以根據需要放在合適的(de)(de)位置(zhi)。 注釋格(ge)式： /* 來(lai)看一個單行注(zhu)釋(shi)和多(duo)行注(zhu)釋(shi)的例子(zi)。 源文件：MessageComment.java //這是一個單行注釋 在(zai)(zai)Java中(zhong)(zhong)，比較特殊(shu)的是javadoc注釋，包(bao)含在(zai)(zai)這部(bu)分中(zhong)(zhong)的注釋可(ke)以通(tong)過(guo)javadoc命令(ling)來自動生(sheng)(sheng)成API文(wen)檔。通(tong)過(guo)javadoc工(gong)具(ju)，可(ke)以保證程序代碼和技術文(wen)檔的同步(bu)。在(zai)(zai)修改了(le)程序中(zhong)(zhong)的注釋后(hou)，只(zhi)需要通(tong)過(guo)javadoc，就可(ke)以方便(bian)地(di)生(sheng)(sheng)成相應(ying)的技術文(wen)檔。 我們知道，在(zai)軟件(jian)開發過(guo)程中(zhong)，文(wen)(wen)檔(dang)(dang)編寫的(de)(de)重要性不(bu)亞于程序(xu)代(dai)碼本身。如果代(dai)碼與文(wen)(wen)檔(dang)(dang)是分(fen)離(li)的(de)(de)，那么在(zai)每次修改代(dai)碼時，都(dou)需要修改相應的(de)(de)文(wen)(wen)檔(dang)(dang)就(jiu)會是一(yi)件(jian)很麻煩的(de)(de)事情。 所以通過(guo)javadoc將代(dai)碼同文(wen)(wen)檔(dang)(dang)“連(lian)接(jie)”起來。在(zai)Java中(zhong)，還有一(yi)種(zhong)特別的(de)(de)注釋方式(shi)：文(wen)(wen)檔(dang)(dang)注釋。利用這種(zhong)注釋，可以從(cong)Java源文(wen)(wen)件(jian)中(zhong)提取這些注釋的(de)(de)內容，來產生HTML格式(shi)的(de)(de)API文(wen)(wen)檔(dang)(dang)。 文(wen)檔(dang)注釋的(de)基(ji)本(ben)格式如下： /** 注意把文檔(dang)注釋(shi)和多行(xing)注釋(shi)區分清(qing)楚，文檔(dang)注釋(shi)的(de)開(kai)始(shi)標記(ji)是(shi)“/**”，而多行(xing)注釋(shi)標記(ji)的(de)開(kai)始(shi)標記(ji)是(shi)“/*”。 由于文(wen)檔注釋重要的(de)一個功能就是用(yong)它來(lai)生成(cheng)HTML格式的(de)API文(wen)檔，因此，很多用(yong)于HTML格式化的(de)HTML標記(ji)(ji)也(ye)可以用(yong)在文(wen)檔注釋中(zhong)，在從這些注釋中(zhong)提取注釋生成(cheng)HTML文(wen)件(jian)的(de)時候(hou)，在生成(cheng)的(de)HTML文(wen)件(jian)中(zhong)，將使(shi)用(yong)這些HTML標記(ji)(ji)來(lai)格式化HTML文(wen)件(jian)內容。常用(yong)的(de)HTML標記(ji)(ji)有(you)<b>…</b>、<code>…</code>等(deng)。關于這些HTML標記(ji)(ji)及其他的(de)HTML標記(ji)(ji)，請讀者參考相關的(de)HTML資料(liao)。 和多行(xing)注(zhu)釋不同的另(ling)一個(ge)地(di)方(fang)是(shi)，文(wen)檔(dang)注(zhu)釋并(bing)不是(shi)可以放(fang)在Java代碼的任何地(di)方(fang)，javadoc工具在從Java代碼中提取(qu)注(zhu)釋生成API文(wen)檔(dang)時，主(zhu)要從以下幾(ji)項內容中提取(qu)信息。 ·包。 因此，文(wen)檔注釋也(ye)應該放到(dao)相應的(de)位置中。 1．文檔注釋位置 （1）類注釋。類注釋用于說明(ming)整(zheng)個(ge)類的(de)功能、特性等，它應該放(fang)在(zai)所有的(de)“import”語句之(zhi)后，在(zai)class定義之(zhi)前。 這個規則也適用于接口（interface）注(zhu)釋(shi)。 （2）方(fang)(fang)法(fa)(fa)(fa)注(zhu)(zhu)釋。方(fang)(fang)法(fa)(fa)(fa)注(zhu)(zhu)釋用來(lai)說明(ming)(ming)方(fang)(fang)法(fa)(fa)(fa)的定(ding)義(yi)(yi)，比(bi)如(ru)，方(fang)(fang)法(fa)(fa)(fa)的參數(shu)、返回值及說明(ming)(ming)方(fang)(fang)法(fa)(fa)(fa)的作用等。方(fang)(fang)法(fa)(fa)(fa)注(zhu)(zhu)釋應(ying)該放在它所描述(shu)的方(fang)(fang)法(fa)(fa)(fa)定(ding)義(yi)(yi)前面。 （3）屬(shu)性注釋。默認情況(kuang)下，javadoc只對公有（public）屬(shu)性和(he)受(shou)保護屬(shu)性（protected）產生文(wen)檔——通常是靜態常量。 （4）包(bao)(bao)注(zhu)(zhu)釋(shi)(shi)(shi)。類、方法、屬(shu)性(xing)的注(zhu)(zhu)釋(shi)(shi)(shi)都(dou)直接放到(dao)Java的源文(wen)(wen)件(jian)中(zhong)，而對于(yu)包(bao)(bao)的注(zhu)(zhu)釋(shi)(shi)(shi)，無法放到(dao)Java文(wen)(wen)件(jian)中(zhong)去，只能通過在包(bao)(bao)對應的目(mu)錄(lu)中(zhong)添加(jia)一(yi)個package.html的文(wen)(wen)件(jian)來達到(dao)這個目(mu)的。當(dang)(dang)生成HTML文(wen)(wen)件(jian)時，package.html文(wen)(wen)件(jian)的<BODY>和</BODY>部分的內容(rong)將會被提(ti)取出(chu)來當(dang)(dang)做包(bao)(bao)的說明。關于(yu)包(bao)(bao)注(zhu)(zhu)釋(shi)(shi)(shi)，后面還(huan)會有更進(jin)一(yi)步的解釋(shi)(shi)(shi)。 （5）概(gai)要注(zhu)(zhu)釋。除了包注(zhu)(zhu)釋外(wai)，還有(you)一(yi)種(zhong)類(lei)型的(de)文(wen)檔無法從Java源文(wen)件(jian)(jian)中(zhong)提取，就(jiu)是(shi)對所有(you)類(lei)文(wen)件(jian)(jian)提供概(gai)要說明的(de)文(wen)件(jian)(jian)。同樣的(de)，也可(ke)以為這類(lei)注(zhu)(zhu)釋單獨(du)新建一(yi)個(ge)HTML文(wen)件(jian)(jian)，這個(ge)文(wen)件(jian)(jian)的(de)名字為“overview.html”，它(ta)的(de)<BODY>和</BODY>標記之間的(de)內(nei)容都會被提取。 2．javadoc標記 在(zai)javadoc注(zhu)釋中，常用(yong)@來表示一(yi)個javadoc標記(ji)，常用(yong)的javadoc標記(ji)如(ru)下： ·@author：作者。 需要(yao)注(zhu)意這些(xie)標(biao)記的(de)使用(yong)是有位(wei)置(zhi)限制的(de)。其中可以出現(xian)在類或者(zhe)接口(kou)文(wen)檔(dang)注(zhu)釋(shi)中的(de)標(biao)記有：@see、@deprecated、@author、@version等(deng)(deng)。可以出現(xian)在方法或者(zhe)構造器文(wen)檔(dang)注(zhu)釋(shi)中的(de)標(biao)記有：@see、@deprecated、@param、@return、@throws、@exception等(deng)(deng)。可以出現(xian)在屬性文(wen)檔(dang)注(zhu)釋(shi)中的(de)有：@see、@deprecated等(deng)(deng)。 3．javadoc命令語法 javadoc的命令行語法如(ru)下： javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ] 參數可以按照任意順序排列(lie)。下面對(dui)這些參數作(zuo)一些說明。 （1）packagenames 包(bao)(bao)列(lie)表：這個選項可以(yi)是一系列(lie)的包(bao)(bao)名（用(yong)(yong)空格隔(ge)開），例如，java.lang java.lang.reflect java.awt。因為javadoc不(bu)遞歸作(zuo)用(yong)(yong)于子包(bao)(bao)，不(bu)允(yun)許對包(bao)(bao)名使用(yong)(yong)通配符；所以(yi)必(bi)須顯式(shi)地列(lie)出(chu)希望建立文檔的每一個包(bao)(bao)。 （2）sourcefiles 源文件(jian)(jian)(jian)列表。這個選項可以是一系(xi)列的源文件(jian)(jian)(jian)名（用空(kong)格(ge)隔開），可以使用通配(pei)符(fu)。javadoc允許4種(zhong)源文件(jian)(jian)(jian)：類源代碼文件(jian)(jian)(jian)、包(bao)描述(shu)文件(jian)(jian)(jian)、總體概(gai)述(shu)文件(jian)(jian)(jian)、其他雜(za)文件(jian)(jian)(jian)。 ·類(lei)(lei)源代碼(ma)文件：類(lei)(lei)或(huo)者接口的源代碼(ma)文件。 ·包(bao)(bao)描(miao)述文(wen)(wen)(wen)件(jian)(jian)：每(mei)一(yi)個包(bao)(bao)都(dou)可以(yi)有自(zi)己的(de)(de)包(bao)(bao)描(miao)述文(wen)(wen)(wen)件(jian)(jian)。包(bao)(bao)描(miao)述文(wen)(wen)(wen)件(jian)(jian)的(de)(de)名稱必(bi)須是 “package.html”，與(yu)包(bao)(bao)的(de)(de).java文(wen)(wen)(wen)件(jian)(jian)放置在一(yi)起。包(bao)(bao)描(miao)述文(wen)(wen)(wen)件(jian)(jian)的(de)(de)內容(rong)通常是使用HTML標記寫的(de)(de)文(wen)(wen)(wen)檔。javadoc執(zhi)行(xing)時將自(zi)動尋找包(bao)(bao)描(miao)述文(wen)(wen)(wen)件(jian)(jian)。如果找到，javadoc將首先對描(miao)述文(wen)(wen)(wen)件(jian)(jian)中(zhong)<body></body>之(zhi)間的(de)(de)內容(rong)進行(xing)處理(li)，然后把(ba)處理(li)結果放到該(gai)包(bao)(bao)的(de)(de)Package Summary頁面(mian)中(zhong)，后把(ba)包(bao)(bao)描(miao)述文(wen)(wen)(wen)件(jian)(jian)的(de)(de)第一(yi)句(ju)（緊(jin)靠(kao)<body>）放到輸出的(de)(de)Overview Summary頁面(mian)中(zhong)，并在語句(ju)前面(mian)加上該(gai)包(bao)(bao)的(de)(de)包(bao)(bao)名。 總(zong)(zong)體(ti)概(gai)(gai)(gai)述(shu)文(wen)(wen)件(jian)(jian)：javadoc可(ke)(ke)(ke)以創建一(yi)個總(zong)(zong)體(ti)概(gai)(gai)(gai)述(shu)文(wen)(wen)件(jian)(jian)描述(shu)整(zheng)個應用(yong)或者所(suo)有包(bao)。總(zong)(zong)體(ti)概(gai)(gai)(gai)述(shu)文(wen)(wen)件(jian)(jian)可(ke)(ke)(ke)以被任意命名，也可(ke)(ke)(ke)以放(fang)(fang)置(zhi)到(dao)任意位(wei)置(zhi)。-overview選項可(ke)(ke)(ke)以指示總(zong)(zong)體(ti)概(gai)(gai)(gai)述(shu)文(wen)(wen)件(jian)(jian)的(de)(de)路(lu)徑(jing)和(he)名稱(cheng)。總(zong)(zong)體(ti)概(gai)(gai)(gai)述(shu)文(wen)(wen)件(jian)(jian)的(de)(de)內(nei)容是使用(yong)HTML標記寫的(de)(de)文(wen)(wen)檔。javadoc在(zai)執(zhi)行(xing)(xing)的(de)(de)時候(hou)，如(ru)果發(fa)現-overview選項，那么它將首先對文(wen)(wen)件(jian)(jian)中(zhong)<body></body>之間(jian)的(de)(de)內(nei)容進行(xing)(xing)處理；然后把(ba)處理后的(de)(de)結果放(fang)(fang)到(dao)輸出的(de)(de)Overview Summary 頁面(mian)的(de)(de)底部；后把(ba)總(zong)(zong)體(ti)概(gai)(gai)(gai)述(shu)文(wen)(wen)件(jian)(jian)中(zhong)的(de)(de)第一(yi)句放(fang)(fang)到(dao)輸出的(de)(de)Overview Summary頁面(mian)的(de)(de)頂部。 ;其他(ta)雜文(wen)(wen)件(jian)(jian)(jian)：這(zhe)(zhe)些文(wen)(wen)件(jian)(jian)(jian)通常是指與javadoc輸出的(de)HTML文(wen)(wen)件(jian)(jian)(jian)相關的(de)一些圖(tu)片文(wen)(wen)件(jian)(jian)(jian)、Java源代碼文(wen)(wen)件(jian)(jian)(jian)（.java）、Java程序（.class）、Java小程序（Applets）、HTML文(wen)(wen)件(jian)(jian)(jian)。這(zhe)(zhe)些文(wen)(wen)件(jian)(jian)(jian)必須放在(zai)doc-files目(mu)錄中。每一個包都(dou)可以有自(zi)己的(de)doc-files目(mu)錄。例如，你希望在(zai)java.awt.Button的(de)HTML文(wen)(wen)檔中使用一幅(fu)按鈕的(de)圖(tu)片（Button.gif）。首(shou)先，必須把圖(tu)片文(wen)(wen)件(jian)(jian)(jian)放到java\awt\doc-files\中；然后在(zai)Button.java文(wen)(wen)件(jian)(jian)(jian)中加入(ru)以下注釋： /** files 包含文件。為了簡(jian)(jian)化javadoc命(ming)令(ling)，可以把需(xu)要建立文檔(dang)的文件名(ming)(ming)和(he)包名(ming)(ming)放(fang)在(zai)一個(ge)或多(duo)個(ge)文本文件中。例如，為了簡(jian)(jian)化以下命(ming)令(ling)： javadoc -d apidoc com.oristand.college com.oristand.school 可以建立一個名稱為mypackage.txt的文(wen)件(jian)，其內容如下： com.oristand.college 然(ran)后執行以下(xia)命令即可： javadoc -d apidoc @mypackage.txt ·options 命令行(xing)選項。 ① public 只顯示公共類及成員。 -classpath classpathlist 指(zhi)定(ding)javadoc查(cha)找“引(yin)用類”的(de)路徑。引(yin)用類是(shi)指(zhi)帶文檔(dang)的(de)類加上它們引(yin)用的(de)任何類。javadoc將搜索指(zhi)定(ding)路徑的(de)所有子目錄，classpathlist可以包含多個路徑（使(shi)用“;”隔開）。 一切就緒(xu)后，就可以使用JDK中的(de)“javadoc”工具來(lai)生成相關的(de)API文檔了。 熱點(dian)鏈接：
1、Java源文件結構詳解 |