本文寫的是什么键畴？
平時總要寫文檔最盅。不寫，代碼無法維護起惕，所以不得不寫涡贱。但是寫文檔費時費力，更可怕的是寫完了讀起來還很費勁惹想，束之高閣问词，總感覺時間浪費掉了，真是苦不堪言嘀粱。
一直以來深受“寫文檔”的折磨激挪，偶然看到一篇神文，接著在網(wǎng)上又查了自動化工具和DSL的理論草穆，這才茅塞頓開灌灾！雖然大部分都沒看懂，但要想做到輕松寫出好文檔悲柱，足矣锋喜！
現(xiàn)在就來說說我是怎么辦到的吧！
要做什么？
我們的最終目的嘿般，是寫出好文檔段标。所以，首先我們要確定：什么是好文檔炉奴。
好文檔就如下圖所示：
上面的文檔好在哪逼庞？
首先，它是文檔瞻赶，讓你知道它的功能赛糟，參數(shù)，一目了然砸逊；
其次璧南，它是程序，你輸入?yún)?shù)就能馬上看到結(jié)果师逸。
所以司倚，我所希望的事，就是在完成代碼后篓像，可以費很少的力氣动知，就生成一個像上文中所說的可調(diào)試文檔。
我們接下來要做的兩件事
生成文檔员辩；
文檔是可調(diào)試的文檔盒粮。
怎么做？
現(xiàn)在要開始做了屈暗，總感覺有些無從下手拆讯，那就先從最具體的事情——目前唯一能看得見的可調(diào)試API開始分析吧。
我們最終要做出的可調(diào)試API是什么樣的呢养叛？
參考之前的效果圖，簡化一些來說宰翅，就是下面這個樣子：
純文字顯示類名弃甥，方法，功能解釋汁讼，輸入?yún)?shù)淆攻；
有一個執(zhí)行按鈕；
有一個區(qū)域顯示執(zhí)行結(jié)果嘿架。
在這個界面中瓶珊，有哪些是變量呢？
1.? ? 類名
2.? ? 方法名
3.? ? 功能說明
4.? ? 參數(shù)數(shù)量
5.? ? 參數(shù)名
6.? ? 執(zhí)行結(jié)果
其中：一個API對應(yīng)著一個類名耸彪，一個方法名伞芹，一個功能說明，多個參數(shù)名，執(zhí)行結(jié)果是執(zhí)行后生成的唱较。
模型分析
根據(jù)以上結(jié)果扎唾，我就可以將這個API抽象出一個模型類了:
一個API包含屬性：類名，類文件所在路徑南缓，方法名胸遇，功能說明以及該方法所需要輸入的參數(shù)。
而一個參數(shù)又包含屬性：參數(shù)名及參數(shù)說明汉形。
事件流
接下來分析一下整個事務(wù)流程纸镊。
一句話流程：
點擊“生成”按鈕，生成類的HTML文檔概疆。
這就是我們要做的事情薄腻，但是說得很不清楚。我們要生成某個類的某個方法對應(yīng)的HTML文檔届案，但是一句話沒有說清庵楷。
現(xiàn)在我們要解釋清楚，于是把它拓展開來楣颠，變成一段話：
配置文件中已指定好待生成文檔的類及其方法了尽纽，點擊“生成按鈕”， 讀取該配置文件童漩，再依次生成文檔弄贿。
我們接下去就這樣繼續(xù)拓展下去，直到把所有步驟都搞清楚矫膨。
最終設(shè)計
整個系統(tǒng)一共有三類頁面：
功能頁：只有一個生成API的按鈕差凹；
類清單頁：將類及其方法列出來，點擊后跳轉(zhuǎn)至API頁面侧馅。
API頁：列出方法說明危尿，可以輸入?yún)?shù)并執(zhí)行該方法，可查看其執(zhí)行結(jié)果馁痴。
三類頁面中谊娇，第二類類清單頁沒有什么功能，只涉及到頁面跳轉(zhuǎn)罗晕，所以只用html實現(xiàn)就行了济欢。
至于功能頁和API頁都采用MVC模式進行設(shè)計。
功能頁
MVC結(jié)構(gòu)
Model:API小渊；
View:make_api_template.php法褥；
Controller:create_api.php
MVC調(diào)用流程
用戶在View層點擊“生成”按鈕后，觸發(fā)Controller酬屉；
Controller中指定了需要生成API的類半等，并調(diào)用這些類中的靜態(tài)方法make_api生成了Model;
Controller利用這些Model生成文檔
API頁
MVC結(jié)構(gòu)
Model：js代碼，目前還未形成獨立的model；
View:生成的html頁酱鸭；
Controller:index.php
MVC調(diào)用流程
用戶在View層輸入某方法的參數(shù)吗垮，點擊“執(zhí)行”按鈕后觸發(fā)Controller；
Controller根據(jù)View頁傳來的參數(shù)凹髓，執(zhí)行方法烁登，得到結(jié)果后返回給View；
View接收到結(jié)果并將其顯示出來
結(jié)語
我實現(xiàn)的版本是CohenBible蔚舀。
類似的工具有很多饵沧，prmd，swagger editor赌躺， apidocjs狼牺，都很好用。
寫這篇文章不是鼓勵大家重復(fù)造輪子礼患，但是自己實現(xiàn)過一遍是钥，會有不一樣的收獲。
我為什么會想到重復(fù)造輪子呢缅叠？
其實最大的原因就是：真的不太會用上面的幾個工具悄泥，只好自己實現(xiàn)，把整個生成文檔的流程走了一遍肤粱。結(jié)果弹囚，回過頭再來看上面的工具，竟然拿來就能用了领曼！如果是按官方的教程走鸥鹉，不知道還要花多少時間，哈哈:)
