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