資訊專欄INFORMATION COLUMN
摘要：本文寫的是什么平時總要寫文檔。所以，我所希望的事，就是在完成代碼后，可以費很少的力氣，就生成一個像上文中所說的可調試文檔。我們接下來要做兩件事生成文檔文檔是可調試的文檔。一句話流程點擊生成按鈕，生成類的文檔。
本文寫的是什么？
平時總要寫文檔。不寫，代碼無法維護，所以不得不寫。但是寫文檔費時費力，更可怕的是寫完了讀起來還很費勁，束之高閣，總感覺時間浪費掉了，真是苦不堪言。
一直以來深受“寫文檔”的折磨，偶然看到一篇神文，接著在網上又查了自動化工具和DSL的理論，這才茅塞頓開！雖然大部分都沒看懂，但要想做到輕松寫出好文檔，足矣！
現在就來說說我是怎么辦到的吧！
要做什么？我們的最終目的，是寫出好文檔。所以，首先我們要確定：什么是好文檔。
好文檔就如下圖所示：
上面的文檔好在哪？
首先，它是文檔，讓你知道它的功能，參數，一目了然；
其次，它是程序，你輸入參數就能馬上看到結果。
所以，我所希望的事，就是在完成代碼后，可以費很少的力氣，就生成一個像上文中所說的可調試文檔。
我們接下來要做兩件事：
1、生成文檔；
2、文檔是可調試的文檔。
現在要開始做了，總感覺有些無從下手，那就先從最具體的事情——目前唯一能看得見的可調試API開始分析吧。
我們最終要做出的可調試API是什么樣的呢？
參考之前的效果圖，簡化一些來說，就是下面這個樣子：
純文字顯示類名，方法，功能解釋，輸入參數；
有一個執行按鈕；
有一個區域顯示執行結果。
在這個界面中，有哪些是變量呢？
類名
列表項目
方法名
功能說明
參數數量
參數名
執行結果
其中：一個API對應著一個類名，一個方法名，一個功能說明，多個參數名，執行結果是執行后生成的。
模型分析根據以上結果，我就可以將這個API抽象出一個模型類了:
一個API包含屬性：類名，類文件所在路徑，方法名，功能說明以及該方法所需要輸入的參數。
而一個參數又包含屬性：參數名及參數說明。
事件流接下來分析一下整個事務流程。
一句話流程：
點擊“生成”按鈕，生成類的HTML文檔。
這就是我們要做的事情，但是說得很不清楚。我們要生成某個類的某個方法對應的HTML文檔，但是一句話沒有說清。
現在我們要解釋清楚，于是把它拓展開來，變成一段話：
配置文件中已指定好待生成文檔的類及其方法了，點擊“生成按鈕”， 讀取該配置文件，再依次生成文檔。
我們接下去就這樣繼續拓展下去，直到把所有步驟都搞清楚。
整個系統一共有三類頁面：
功能頁：只有一個生成API的按鈕；
類清單頁：將類及其方法列出來，點擊后跳轉至API頁面。
API頁：列出方法說明，可以輸入參數并執行該方法，可查看其執行結果。
三類頁面中，第二類類清單頁沒有什么功能，只涉及到頁面跳轉，所以只用html實現就行了。
至于功能頁和API頁都采用MVC模式進行設計。
MVC結構
Model:API；
View:make_api_template.php；
Controller:create_api.php
MVC調用流程
用戶在View層點擊“生成”按鈕后，觸發Controller；
Controller中指定了需要生成API的類，并調用這些類中的靜態方法make_api生成了Model;
Controller利用這些Model生成文檔
MVC結構
Model：js代碼，目前還未形成獨立的model；
View:生成的html頁；
Controller:index.php
MVC調用流程
用戶在View層輸入某方法的參數，點擊“執行”按鈕后觸發Controller；
Controller根據View頁傳來的參數，執行方法，得到結果后返回給View；
View接收到結果并將其顯示出來
我實現的版本是CohenBible。
類似的工具有很多，prmd，swagger editor， apidocjs，都很好用。
寫這篇文章不是鼓勵大家重復造輪子，但是自己實現過一遍，會有不一樣的收獲。
我為什么會想到重復造輪子呢？
其實最大的原因就是：真的不太會用上面的幾個工具，只好自己實現，把整個生成文檔的流程走了一遍。結果，回過頭再來看上面的工具，竟然拿來就能用了！如果是按官方的教程走，不知道還要花多少時間，哈哈:)
文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。
轉載請注明本文地址：http://m.specialneedsforspecialkids.com/yun/21148.html
摘要：本文寫的是什么平時總要寫文檔。所以，我所希望的事，就是在完成代碼后，可以費很少的力氣，就生成一個像上文中所說的可調試文檔。我們接下來要做兩件事生成文檔文檔是可調試的文檔。一句話流程點擊生成按鈕，生成類的文檔。 本文寫的是什么？ 平時總要寫文檔。不寫，代碼無法維護，所以不得不寫。但是寫文檔費時費力，更可怕的是寫完了讀起來還很費勁，束之高閣，總感覺時間浪費掉了，真是苦不堪言。 一直以來深受...
摘要：語法更近似于移動端。當參數為兩個時，等同于，繪制光滑二次貝塞爾曲線。有些精通的同學這時候可能就要問我了，不對啊，二次貝塞爾曲線和光滑三次貝塞爾曲線的參數都是個，你這里沒有光滑三次啊因為開發的同學留坑沒寫了呀微笑。和則是用于指定旋轉的原點。 技術背景 在移動應用的開發過程中，繪制基本的二維圖形或動畫是必不可少的。然而，考慮到Android和iOS均有一套各自的API方案，因此采用一種更普...
摘要：記錄日期為年月日阿里云域名購買及備案在阿里云購買域名和服務器以后，先進行服務器備案，生成備案號，然后進行實名采集認證等操作，全部結束以后，才可以進行域名備案申請。提交資料需要用阿里云手機提交，一個工作日左右會有人員和你聯系，確認信息。 這篇文章內容比較雜，但是這次我準備多寫些干貨，自己備查，也方便別人參考。記錄日期為2019年06月21日 阿里云域名購買及備案 在阿里云購買域名和服務器...
閱讀 2936·2021-10-14 09:43
閱讀 2878·2021-10-14 09:42
閱讀 4661·2021-09-22 15:56
閱讀 2368·2019-08-30 10:49
閱讀 1593·2019-08-26 13:34
閱讀 2381·2019-08-26 10:35
閱讀 602·2019-08-23 17:57
閱讀 2027·2019-08-23 17:15
