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