對于軟件開發(fā)人員來說，查看API應該是基本的能力。但是我們自己怎么定義出我們自己的API？對于Android開發(fā)者而言，寫代碼是基本的，但是代碼我們不只是寫，還要理解，一份好的代碼不是自己理解就OK的，最重要的是你寫的代碼后續(xù)維護的人要理解，(如果別人不理解，那就會在心里問候你全家啦，呵呵)所以能夠讓別人看懂你的代碼是很重要的。因此我們就要學會給我們的代碼加上注釋，但是怎么讓我們的注釋隨生成的javadoc一起生效呢，這里的生效是我們自定義的注釋，系統(tǒng)的會自動生成的！下面就來詳細討論注釋的使用。
注：本文章不介紹標記的使用。重點介紹如何生成javadoc和自定義標記。
javadoc 標記有如下一些：
| 標記 | 用于 | 作用 |
|---|---|---|
| @author | 對類的說明 | 標明開發(fā)該類模塊的作者 |
| @version | 對類的說明 | 標明該類模塊的版本 |
| @see | 對類、屬性、方法的說明 | 參考轉向，也就是相關主題 |
| @param | 對方法的說明 | 對方法中某參數(shù)的說明 |
| @return | 對方法的說明 | 對方法返回值的說明 |
| @exception/throws | 對方法的說明 | 對方法可能拋出的異常進行說明 |
一、使用Eclipse工具生成API和自定義javadoc。
例如下面的代碼：
/**
* @author xlou
* @date 2017-12-8
* @version v1.0
*/
public interface IJavadocIntenerface {
/**
* @param name
* @param age
* @return boolean ture/false
* @throws NullPointerException 如果傳入的參數(shù)為Null，則會拋出NullPointerException
*/
boolean generateJavaDoc(String name,int age) throws NullPointerException;
}
對于上面的代碼是很簡單的例子，現(xiàn)在我們需要將上面的代碼生成javadoc，詳細過程可以參考資料：jingyan.baidu.com/article/597a0643485c11312b5243c7.html。
詳細過程如下：
-
點擊eclipse的【Project】菜單，選擇【Generate JavaDoc】選項。
image.png - 選擇您要生成JavaDoc的工程
- 選擇哪些級別的內容生成JavaDoc，默認為public，如果選擇private則會全部內容都生成。
- 選擇doc的生成位置，默認為工程目錄下，建議不要修改。
-
點擊【Next】按鈕
image.png - 勾選Document Title，然后填寫文檔標題。
-
點擊【Next】按鈕
image.png - 選擇使用的jdk版本
-
點擊【Finish】按鈕
image.png
最后項目下生成一個【doc】的目錄，里面存放著javadoc文檔。
image.png
打開doc目錄，用瀏覽器打開index.html。
image.png
對于以上的代碼我們生成的DOC文檔內容如下：jdoc.JPG
到這里我們細心點可以發(fā)現(xiàn)，我們定義的@date沒有生成，因為這是我們自己定義的，因此需要我們在生成Javadoc的時候進行配置。配置工作在以上第8、9步的時候，如下圖配置：jdoc.JPG
配置后生產(chǎn)的API文檔如下：jdoc.JPG
從上圖可以看出我們自定義的@date就生成啦，如果要自定義多個怎么辦呢？沒關系，繼續(xù)在后面追加內容就要可以，如：-tag version:a:"version:" -tag date:a:"date:"
-
如何使用Eclipse配置注釋模板?
到這里我們詳細介紹如何使用Eclipse配置注釋模板，為什么要介紹模板呢？一句話：為了方便（哪里需要那么多理由啊，配置模板需要理由嗎）。下面我們用類的注釋來詳解配置類的注釋模板，函數(shù)的注釋模板大同小異，這里就不一一介紹啦。
- 第一步，我們需要類注釋模板的XML文件，我們定義了一個類的xml文件，xml文件名為Types.xml，內容如下：
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<templates>
<template autoinsert="false" context="typecomment_context" deleted="false" description="Comment for created types" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.typecomment" name="typecomment">
/**
* @Description
* @ID
* @InterfaceName
* @author
* @date ${date}
* @version
*/
</template>
</templates>
-
選擇上圖中的Import按鈕，導入我們的Types.xml文件后就可以啦，最終成功后如下圖： jdoc.JPG
如上面紅色框中就是我們自定義的模板，然后我們在類或者接口添加doc注釋的時候就會自動生成如上模板的注釋。
二、使用Android Studio生成API和自定義javadoc
現(xiàn)在我們詳細介紹使用Android Studio來做上面的工作。利用Android Studio 生成API步驟如下：可以參考www.cnblogs.com/moneymanymany/p/5157317.html 。
首先介紹自定義注釋模板以及快捷鍵：
-
通過 File –>Settings 或者 HotKey Ctrl + Alt + S 打開 Settings面板，如下圖
-
點擊 Editor下的Live Templates。如下圖，顯示的是Android Studio為開發(fā)者提供的默認模板及快捷鍵。
-
為了自定義注釋模板，點擊右上角的“+”,選擇Template Group創(chuàng)建一個自定義Template Group
-
選擇創(chuàng)建好的Template Group, 在點擊“+”,選擇Live Template創(chuàng)建一個自定義的Template
-
選擇創(chuàng)建好的Templat，如下圖。在Abbreviation內輸入字符串，例如decl。在Description內填寫描述信息。
-
在點擊Template text輸入框下方的Define，選擇快捷鍵起作用的情況，選擇Declaration，在函數(shù)前面輸入decl后按回車即可以按模板生產(chǎn)注釋
-
在Template text內輸入自定的注釋模板，$xxx$這類的變量可以通過Edit variables來設置其含義
-
如果要生成JavaDoc，就要按規(guī)則書寫函數(shù)注釋模板，規(guī)則可以參考 Editor –> Code Style –>Java –>JavaDoc
最后生成javadoc。
-
點擊Tools –>Generate JavaDoc 來生成Java Doc
-
界面選擇如下：jdoc.JPG
-
如果要自定義注釋和設置編碼格式，如下：jdoc.JPG
- 如果生產(chǎn)Java Doc失敗，檢查 Include jdk and library sources in –sourcepath是否勾選。
Other command line arguments，設置Android SDK的bootclasspath和編碼
1. -bootclasspath D:\AndroidSDK\sdk\platforms\android-23
2. -encoding utf-8
3. -charset utf-8
