我們如何好的生成規範的API文檔,我們就要使用JAVADOC哦。要自己手動去寫API的也不介意哈。不過我覺得一個核心框架一定要寫好註釋做好包。這個就是絕對的經典。做好質量和友善的規範,估計用戶纔會很好使用您努力汗水的結晶。
爲了正確的編寫出來API文檔,你必須在每個被導出的類,接口,方法和域聲明做好文檔註釋。
每個方法的文檔應該清晰的描述他與客戶的關係以及之間應該遵守的約定。但是也有例外的,除了那種專門被用來繼承設計的方法可以脫離這樣的約定,但是要告訴這個方法是做什麼的,怎麼做的就可以不用說了。我們在寫方法文檔註釋時,一定要列舉出來前置條件和後置條件,所謂前置條件就是用戶能夠調用這個方法應該滿足的條件。後置條件是當方法調用完成後,哪些條件必須滿足。
/**
* Return the DataSource to use for retrieving Connections.
* <p>This implementation returns the passed-in DataSource as-is.
* @param originalDataSource the DataSource as configured by the user
* on LocalSessionFactoryBean
* @return the DataSource to actually retrieve Connections from
* (potentially wrapped)
* @see LocalSessionFactoryBean#setDataSource
*/
protected DataSource getDataSourceToUse(DataSource originalDataSource) {
return originalDataSource;
}
這樣代碼絕對值得學習(spring2.5-src.jar)
我正在朝這樣的方向去實現,努力讓一個年輕人變成大神。5555大神。要的是一種態度和精神,中國不少程序員缺乏的就是這樣態度。
這個還有一點需要注意下,我們的方法如果有副作用我們也應該好好註釋出來,這點很重要的。例如:這個方法有線程安全問題。比如說他開啓了另外一個後臺線程。你應該在註釋中告訴用戶。
*在整個文檔註釋中採用都是HTML元素,所以比如說特殊符號要使用轉義字符。比如“<”使用$lt;等。還有在文檔描述的第一句話內部不要使用句號,因爲句話會讓第一句話直接結束掉。比如:“a is b new object,b.admin create by ”這樣的只能產生"a is b new object,b".
要用就用轉義字符吧”.“.
說了這麼多如何使用javadoc生成標準的註釋API。簡單就用eclipse吧方法如下:
使用eclipse生成文檔(javadoc)主要有三種方法:
1,在項目列表中按右鍵,選擇Export(導出),然後在Export(導出)對話框中選擇java下的javadoc,提交到下一步。
在Javadoc Generation對話框中有兩個地方要注意的:
javadoc command:應該選擇jdk的bin/javadoc.exe
destination:爲生成文檔的保存路徑,可自由選擇。
按finish(完成)提交即可開始生成文檔。
2,用菜單選擇:File->Export(文件->導出),
剩下的步驟和第一種方法是一樣的。
3,選中要生成文檔的項目,然後用菜單選擇,
Project->Generate Javadoc直接進入Javadoc Generation對話框,剩餘的步驟就和第一種方法在Javadoc Generation對話框開始是一樣的。
看了說明鬼都會生成API啦呵呵。