導(dǎo)語(yǔ)：
我們知道javadoc是內(nèi)嵌于JDK中的，因此遵循javadoc規(guī)范肯定就是java注釋的正統(tǒng)，有了javadoc幫助生成API文檔是非常實(shí)用的。
（學(xué)習(xí)視頻分享：java視頻教程）
1、什么是注釋
注釋是為了使代碼更具有可讀性，降低團(tuán)隊(duì)合作的交流成本。在一個(gè)團(tuán)隊(duì)中，你的代碼更清晰、更易讀，更規(guī)范，那么升職加薪肯定是你的，因?yàn)槟憧梢约嫒莞嗟娜恕?br>前段時(shí)間聽(tīng)到一個(gè)說(shuō)法：你的代碼寫(xiě)的只有你一個(gè)人看得懂，那你就是那個(gè)不可或缺的人。說(shuō)這話(huà)的人就是腦殘，寫(xiě)的代碼只有自己看的懂得話(huà)，大家都不待見(jiàn)，活的像孫子一樣，難道大家都需要孫子嗎？
2、常用注釋快捷鍵
注釋一行：//我是行內(nèi)容
快捷鍵：ctrl+/ 反操作：ctrl+/注釋一塊：/*我是塊內(nèi)容*/
快捷鍵：ctrl+shift+/ 反操作：ctrl+shift+\javadoc可識(shí)別的注釋?zhuān)?/p>
/** * 我是注釋 * 我也是注釋 * 我還是注釋?zhuān)覀兌寄鼙籮avadoc識(shí)別 */
3、javadoc規(guī)范
遵循javadoc規(guī)范，我們就可以使用javadoc命令，生成非常直觀(guān)易讀的API文檔，非常方便。
我們?cè)诔绦蛑谐霈F(xiàn)的注釋可以有意識(shí)地分為兩種，一種是簡(jiǎn)易的注釋?zhuān)o我們自己看的，一種是符合javadoc規(guī)范的注釋?zhuān)康氖巧梢鬃x的文檔。
仔細(xì)閱讀生成的API文檔，有三部分需要我們說(shuō)明，如圖：
上面紅框的內(nèi)容都是我添加的注釋?zhuān)且粋€(gè)簡(jiǎn)單的Hello類(lèi)，源碼如下，感興趣可以自己去試試：
/**
* @author XXXX
* @version 創(chuàng)建時(shí)間：2021年1月21日 下午3:22:01
*
*/
public class Hello {
/**
* main()方法簡(jiǎn)述(后面這個(gè)dot必不可少).
* <p>這就是為了測(cè)試注釋<br>
* 沒(méi)什么好說(shuō)明的，只為了說(shuō)明能出現(xiàn)在這里
* @param args 就是系統(tǒng)配的，沒(méi)啥說(shuō)的
*
*/
public static void main(String[] args) {
// TODO Auto-generated method stub
System.out.println("hello");
}
/**
* havaReturn方法就是為了測(cè)試javadoc注釋規(guī)范的.
* <p>我發(fā)現(xiàn)只有有返回值的方法才可以使用return標(biāo)簽<br>
* 沒(méi)有return硬是要用，只會(huì)在javadoc時(shí)候報(bào)錯(cuò)
* @param a 輸入的第一個(gè)int類(lèi)型的參數(shù)
* @param b 輸入的第二個(gè)int類(lèi)型的參數(shù)
* @return add 兩個(gè)數(shù)的和運(yùn)算結(jié)果
*/
public int haveReturn(int a,int b){
int add=0;
add=a+b;
return add;
}
}有幾個(gè)要點(diǎn)需要指出：
要想API文檔出現(xiàn)作者和版本，不僅要在程序注釋中添加@author和@version（需要說(shuō)明的是，在程序多個(gè)地方注釋@author也只會(huì)在最終文檔中顯示一次，我建議只注釋一次），還要在編譯的時(shí)候在dos命令中指出：
javadoc -d folder -version -author Hello.java
其中-d folder意思是你把生成的API文檔（其實(shí)是很多網(wǎng)頁(yè)組成的）放在folder文件夾中，當(dāng)然folder也可以是個(gè)路徑
方法概要 與 方法詳細(xì)資料 怎么區(qū)分呢？
/**
* main()方法簡(jiǎn)述(后面這個(gè)dot必不可少).
* <p>這就是為了測(cè)試注釋<br>
* 沒(méi)什么好說(shuō)明的，只為了說(shuō)明能出現(xiàn)在這里
* @param args 就是系統(tǒng)配的，沒(méi)啥說(shuō)的
*
*/
public static void main(String[] args) {
// TODO Auto-generated method stub
System.out.println("hello");
}你一定發(fā)現(xiàn)關(guān)于方法的注釋都是一大坨，javadoc如何提取概要呢？沒(méi)錯(cuò)，就只靠一個(gè)dot(.)，觀(guān)察我注釋里面提到的那個(gè)dot，那就是提取概要的關(guān)鍵，dot之前是概要，所有的都是詳細(xì)介紹（詳細(xì)介紹是包含概要的）
如何控制生成的文檔中的注釋排版
我們?cè)诔绦蛑心芸刂谱〉木褪亲⑨尩呐虐妫沁@種排版并不被javadoc識(shí)別，javadoc發(fā)現(xiàn)一行注釋?zhuān)蝗サ?和空格之后，就一股腦傳過(guò)去，注意到生成的文檔是HTML類(lèi)型的，所以只要在程序中注釋HTML語(yǔ)法，就能實(shí)現(xiàn)編輯API文檔格式，不要擔(dān)心太困難，因?yàn)槲覀冎皇怯靡恍┖?jiǎn)單的HTML語(yǔ)法，比如段落
，換行
這些就可以，畢竟注釋也不會(huì)很長(zhǎng)。
@param 參數(shù)1 說(shuō)明 （注意格式）
@return 返回值 說(shuō)明（注意格式）
有返回值就寫(xiě)，沒(méi)返回值就不用寫(xiě)，寫(xiě)了反而會(huì)報(bào)錯(cuò)
其實(shí)寫(xiě)類(lèi)注釋、方法注釋非常簡(jiǎn)單，只要在類(lèi)、方法前敲擊/**，再按回車(chē)，系統(tǒng)就會(huì)自動(dòng)添加，并且系統(tǒng)如何添加也是我們可以修改的
如何修改新建文件時(shí)出現(xiàn)的內(nèi)容，如何使自動(dòng)補(bǔ)全的注釋受我們控制（待辦）
我們從標(biāo)準(zhǔn)類(lèi)文件中看到這個(gè)：
我們都知道，out是System類(lèi)的屬性（字段），它是PrintStream類(lèi)型的，類(lèi)PrintStream中定義了很多方法，這些自然也是out的方法，因此在定義out的時(shí)候，它前面的注釋中就有很多@see,這就是使用@see注釋最好的地方，我們推薦在定義類(lèi)的字段時(shí)，如果字段是復(fù)合類(lèi)型的（特別是自定義的復(fù)合類(lèi)型），那么就在前面注釋@see,這樣有兩方面的好處，請(qǐng)看圖：
相信這兩張圖你都不陌生，第一個(gè)是寫(xiě)程序時(shí)候光標(biāo)停留可以出現(xiàn)的提示，如果你按照javadoc規(guī)范來(lái)寫(xiě)注釋?zhuān)敲茨阕约簩?xiě)的程序也會(huì)出現(xiàn)這些極有幫助的提示。第二個(gè)是java8 API文檔關(guān)于String類(lèi)里的out字段的詳細(xì)描述，這也是@see的功勞，你寫(xiě)了@see，你自己的項(xiàng)目API文檔中也有這樣的注釋。
相關(guān)推薦：java入門(mén)教程
Atas ialah kandungan terperinci javadoc規(guī)范介紹. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!
Alat AI Hot
Undress AI Tool
Gambar buka pakaian secara percuma
Undresser.AI Undress
Apl berkuasa AI untuk mencipta foto bogel yang realistik
AI Clothes Remover
Alat AI dalam talian untuk mengeluarkan pakaian daripada foto.
Clothoff.io
Penyingkiran pakaian AI
Video Face Swap
Tukar muka dalam mana-mana video dengan mudah menggunakan alat tukar muka AI percuma kami!
Artikel Panas
Alat panas
Notepad++7.3.1
Editor kod yang mudah digunakan dan percuma
SublimeText3 versi Cina
Versi Cina, sangat mudah digunakan
Hantar Studio 13.0.1
Persekitaran pembangunan bersepadu PHP yang berkuasa
Dreamweaver CS6
Alat pembangunan web visual
SublimeText3 versi Mac
Perisian penyuntingan kod peringkat Tuhan (SublimeText3)
Konvensyen penamaan pembolehubah diperlukan dalam pembelajaran Python
Jan 20, 2024 am 09:03 AM
Konvensyen penamaan pembolehubah yang perlu anda ketahui semasa mempelajari Python Aspek penting semasa mempelajari bahasa pengaturcaraan Python ialah mempelajari cara menamakan dan menggunakan pembolehubah dengan betul. Pembolehubah ialah pengecam yang digunakan untuk menyimpan dan mewakili data. Konvensyen penamaan pembolehubah yang baik bukan sahaja meningkatkan kebolehbacaan kod anda, tetapi juga mengurangkan kemungkinan ralat. Artikel ini akan memperkenalkan beberapa konvensyen penamaan pembolehubah yang biasa digunakan dan memberikan contoh kod yang sepadan. Gunakan Nama Bermakna Nama pembolehubah harus mempunyai makna yang jelas dan dapat menerangkan data yang disimpan dalam pembolehubah. Menggunakan nama yang bermakna membolehkannya
Bagaimanakah anda boleh memahami prinsip reka bentuk dan matlamat di sebalik spesifikasi kod PHP terkini dengan membaca kod sumbernya?
Sep 05, 2023 pm 02:46 PM
Bagaimanakah anda boleh memahami prinsip reka bentuk dan matlamat di sebalik spesifikasi kod PHP terkini dengan membaca kod sumbernya? Pengenalan: Apabila menulis kod PHP berkualiti tinggi, adalah sangat penting untuk mengikuti piawaian pengekodan tertentu. Melalui spesifikasi kod, kebolehbacaan, kebolehselenggaraan dan kebolehskalaan kod boleh dipertingkatkan. Untuk bahasa PHP, terdapat spesifikasi kod yang diterima pakai secara meluas, iaitu PSR (PHPStandardsRecommendations). Artikel ini akan memperkenalkan cara membaca kod sumber spesifikasi kod PHP terkini
Analisis kekunci pintasan pemformatan PyCharm: cara cepat menyatukan gaya kod
Jan 27, 2024 am 10:38 AM
Seragamkan gaya kod dengan cepat: Kebolehbacaan dan ketekalan kod penghuraian kekunci pintasan berformat PyCharm adalah sangat penting untuk pengaturcara. Di bawah premis mengikut spesifikasi gaya pengekodan tertentu, menulis kod bersih boleh menjadikan projek lebih mudah untuk diselenggara dan difahami. Sebagai persekitaran pembangunan bersepadu yang berkuasa, PyCharm menyediakan kekunci pintasan untuk membantu kami memformat kod dengan cepat. Artikel ini akan memperkenalkan beberapa kekunci pintasan yang biasa digunakan dalam PyCharm, serta penggunaan dan kesan khususnya. 1. Inden automatik kod (Ctrl
Apakah standard untuk antara muka API?
Feb 23, 2024 pm 08:15 PM
Spesifikasi antara muka API (Application Programming Interface) merujuk kepada satu siri garis panduan dan spesifikasi yang mentakrifkan dan menentukan antara muka API dalam pembangunan perisian. Tujuan spesifikasi antara muka API adalah untuk memastikan kesalingoperasian dan ketekalan antara komponen perisian yang berbeza. Artikel ini akan memperkenalkan beberapa aspek penting spesifikasi antara muka API. Konvensyen penamaan antara muka Nama antara muka API hendaklah jelas, ringkas dan konsisten serta boleh menyatakan fungsi dan tujuannya dengan tepat. Penamaan konvensyen harus mengikut amalan industri dan konvensyen dalaman pasukan pembangunan, dan elakkan menggunakan istilah yang tidak jelas dan mengelirukan. ini
Bagaimana untuk menyelesaikan masalah penggunaan ruang inden yang tidak teratur dalam kod Python?
Jun 24, 2023 pm 09:03 PM
Python adalah bahasa pengaturcaraan yang sangat popular Ia digemari oleh lebih ramai orang kerana kesederhanaan, kemudahan pemahaman, dan kemudahan pembelajaran. Dalam Python, format lekukan dan kod adalah sangat penting Jika digunakan secara tidak teratur, ia akan menjejaskan kebolehbacaan dan kebolehselenggaraan kod. Artikel ini bertujuan untuk memperkenalkan beberapa kaedah untuk menyelesaikan masalah ruang lekukan yang tidak teratur dalam kod Python. Menggunakan alat automatik Dalam pengaturcaraan Python, adalah sangat penting untuk mematuhi piawaian pengekodan Setiap lekukan dalam kod harus menggunakan bilangan ruang yang sama. Jika anda mengubah suai baris demi baris secara manual
Amalan dan norma pengekodan biasa dalam bahasa Go
Jun 01, 2023 am 09:51 AM
Dengan pempopularan dan penggunaan bahasa Go secara beransur-ansur, amalan pengekodan dan spesifikasi bahasa Go juga telah mendapat lebih banyak perhatian dan perhatian. Artikel ini akan memperkenalkan amalan dan spesifikasi pengekodan biasa dalam bahasa Go untuk membantu pembangun menulis kod Go berkualiti tinggi. Pemformatan kod Pemformatan kod dalam bahasa Go ialah spesifikasi dan amalan yang sangat penting. Bahasa Go menyediakan alat pemformatan kod rasmi - goimports, yang boleh melaraskan lekukan, ruang, tanda petikan, dsb. kod secara automatik, dan juga boleh mengimport pakej yang tidak diimport secara automatik. Guna goimpo
Piawaian penulisan PHP dan amalan kerja berpasukan: meningkatkan kecekapan pembangunan projek
Aug 25, 2023 pm 11:27 PM
Amalan spesifikasi penulisan PHP dan kerjasama pasukan: meningkatkan kecekapan pembangunan projek Dalam pembangunan projek, spesifikasi penulisan adalah amalan yang diperlukan. Piawaian penulisan yang baik boleh meningkatkan kebolehbacaan dan kebolehselenggaraan kod, mengelakkan ralat peringkat rendah dan membolehkan ahli pasukan bekerjasama dengan lebih baik. Artikel ini akan memperkenalkan beberapa amalan menulis spesifikasi dalam PHP dan meneroka cara menggunakan spesifikasi ini dalam kerja berpasukan untuk meningkatkan kecekapan pembangunan projek. Menggunakan standard PSR-2 PSR-2 ialah standard untuk spesifikasi kod PHP Ia menetapkan satu set format kod, komen,
Penjelasan terperinci tentang contoh dok antara bahasa Go dan antara muka Tencent Cloud
Jul 06, 2023 pm 05:06 PM
Contoh terperinci dok antara bahasa Go dan antara muka Tencent Cloud Dalam beberapa tahun kebelakangan ini, dengan perkembangan teknologi pengkomputeran awan, penyedia perkhidmatan awan telah menjadi pilihan pertama banyak perusahaan dan pembangun. Sebagai penyedia perkhidmatan awan terkemuka di China, Tencent Cloud menyediakan satu siri antara muka API untuk dipanggil oleh pembangun bagi memudahkan pembangun menggunakan fungsi perkhidmatan awannya yang kaya. Sebagai bahasa pengaturcaraan yang mudah dan cekap, bahasa Go semakin digemari oleh pembangun. Artikel ini akan memperkenalkan secara terperinci cara menggunakan bahasa Go untuk menyambung dengan antara muka Tencent Cloud dan memberikan kod contoh khusus. 1. Peringkat awal
