如何寫出好API文件

寫程式庫會需要寫 API 告訴使用者如何使用。
之前看過的  API 文件有些缺點。

• Doxygen：常常太簡陋。
• 仔細思考，問題出在寫的內容太少。
• 全部整理成為一個文件：覺得超長看不下去。
• 廠商的 reference manual 多半這樣寫。
• 仔細思考，因為用文件的唸法照順序念，當然太長。
• MSDN：很適合
• 內容很多，但是分頁下去後，可以只看想看的部分就好。

原來之前覺得說明不夠清楚，不是格式不好，而是因為說的不夠多。換句話說，用doxygen只要寫的更多，也會有 MSDN 的品質。

所以寫 API 文件的 SOP 如下：

• 寫模組列表頁，放模組列表，列表裡模組名稱加超連結。
• 為每一個模組寫獨立的模組頁，裡面有類別列表，列表裡類別名稱加超連結。有連結回模組列表頁。
• 為每一個類別寫獨立的類別頁，裡面有函數列表，列表裡函數名稱加超連結。有連結回模組頁。
• 為每一個函數寫獨立的函數頁，函數的頁面要按照範本。有連結回類別頁。
• 有usage、參數、remark、see also等等
• 不用要求到每一頁都一樣。因為使用者一次只會看到一頁。
• see also 包含回上層的超連結
• 這很重要，少了它就無法順利瀏覽。

範例

Introduction
    // 幾句話說明這個程式庫能做什麼。


Table of Contents
    // 讓 Word 自動產生


ChangeLog
    // 版本之間差異

date	description
xxxx/xx/xx	Add XXX
xxxx/xx/xx	First version

Architecture
    // 一張圖畫大架構


Modules
    // 表格列出所有模組，這一頁是總目錄。點 module name 可以前往 module 的頁面。

module	description
module1	used for XXX
module2	used for YYY

module 1
    // 表格列出所有class。點 class name 可以前往 class 的頁面。

class	description
class1	used for XXX
class2	used for YYY

    see also
        Modules << 可以點這裡回上層



class1
    // 表格列出所有function。點 function name 可以前往 function 的頁面。　　

functions	description
function1	used for XXX
function2	used for YYY

    see also
        /module1   << 可以點這裡回上層



function1
    Usage
         function1(arg1, arg2)
    Parameters
    Remark
    see also
        /class1   << 可以點這裡回上層