資訊專(zhuān)欄INFORMATION COLUMN
摘要：我們?cè)趯?duì)現(xiàn)在較主流的五個(gè)文檔工具分別作了調(diào)研和嘗試，得到結(jié)論如下工具優(yōu)點(diǎn)缺點(diǎn)提供了完整的模板開(kāi)發(fā)事件觸發(fā)等接口，使用非常靈活。至此，的環(huán)境部署已經(jīng)全部完成了。
字?jǐn)?shù)：981
閱讀時(shí)間：5分鐘
選型依據(jù)? 在經(jīng)歷了數(shù)個(gè)上線(xiàn)的項(xiàng)目之后，筆者所在的團(tuán)隊(duì)已經(jīng)沉淀了一個(gè)相對(duì)穩(wěn)定版本的前端框架。因此，我們需要出具一套框架API文檔，以便公司其他成員的使用和框架的后期維護(hù)。我們?cè)趯?duì)現(xiàn)在較主流的五個(gè)文檔工具：JSDoc 3、YUIDoc、Dox、Docco、JSDuck分別作了調(diào)研和嘗試，得到結(jié)論如下：
| 工具 | 優(yōu)點(diǎn) | 缺點(diǎn) |
|---|---|---|
| JSDoc3 | 提供了完整的模板開(kāi)發(fā)、事件觸發(fā)等接口，使用非常靈活。 | 對(duì)代碼要求比較嚴(yán)格，學(xué)習(xí)曲線(xiàn)較高。 |
| YUIDoc | 不止支持JS語(yǔ)言，更加抽象，如果同時(shí)使用了 Ruby/PHP/Python等語(yǔ)言YUI都可以使用。 | 功能更加抽象，具體實(shí)現(xiàn)方面考慮不全。 |
| Dox | 輕量級(jí)、高度可定制化，兼容JSDoc3語(yǔ)法。 | 后期會(huì)有較多問(wèn)題需要自己解決。 |
| Docco | 行間注釋方式，更注重實(shí)現(xiàn)過(guò)程的文檔 | 不太適合API注釋 |
| JSDuck | 代碼實(shí)時(shí)修改、語(yǔ)法靈活、支持MarkDown語(yǔ)法，支持查看源碼并且文檔可讀性較高，最主要的是上手非?？臁?/td> | 可定制化支持不足，略顯臃腫。 |
? 我們選型的條件權(quán)重由高到低依次是：
? 1.較強(qiáng)的可讀性。
? 2.較低的學(xué)習(xí)成本。
? 3.注釋語(yǔ)義的豐富程度，是否滿(mǎn)足我們的需求。
? 4.是否足夠靈活。
? JSDuck可讀性較高，上手較快，并且使用JSDuck工具生成的extJS文檔的成功有目共睹，綜合考量，我們最終選擇了JSDuck工具。
環(huán)境部署? 由于JSDuck需要依賴(lài)ruby環(huán)境，所以環(huán)境部署分為以下三步：
? 1.安裝ruby
? 2.安裝devkit
? 3.安裝JSDuck
? 第一步，安裝ruby ：
? 下載地址：https://rubyinstaller.org/dow...
?
? 選擇符合本機(jī)電腦的安裝包下載即可。
? 第二步，安裝devkit：
? 下載地址：https://rubyinstaller.org/dow...
?
? 選擇符合本機(jī)電腦的安裝包下載即可。注意devkit安裝目錄不要有中文或者特殊字符，然后在安裝根目錄下執(zhí)行cmd命令 ruby dk.rb init。這時(shí)，我們會(huì)在當(dāng)前目錄下看到一個(gè)config.yml文件，編輯該文件，添加ruby目錄配置。例如，筆者的ruby是安裝在 F:/Ruby22-x64 目錄下，就做如下圖修改即可：
?
? 安裝成功后，執(zhí)行命令 ruby dk.rb install 命令。
? 第三步：安裝JSDuck
? 執(zhí)行命令 gem install jsduck 命令安裝jsduck。
? 至此，JSDuck的環(huán)境部署已經(jīng)全部完成了。
第一個(gè)文檔? 準(zhǔn)備工作終于做完了，那還等什么，當(dāng)然是馬上開(kāi)始看看我們成果如何啦！
? 在 G:test-jsduck目錄下，創(chuàng)建一個(gè)test.js文件，編寫(xiě)如下代碼：
/**
* @class 人類(lèi)
* @author lsjcoder
* @docauthor lsjcoder
*/
function People(){
/**
*
* @property {String} 姓名
*/
this.name = "lsjcoder";
/**
* 吃飯
* @method
* @param food {String} 食物名稱(chēng)
* @return {Boolean} 是否吃過(guò)
*/
this.eat = function(food){
if(food != null){
return true;
}else{
return false;
}
}
}
? 然后在cmd中運(yùn)行命令 jsduck "G:test-jsducktest.js" --output=G:test-jsduckdoc ，工具就自動(dòng)將文檔生成到目錄 G:test-jsduckdoc 下，直接運(yùn)行里面的 index.html 文件就可以看到如下成果圖：
? 是不是非常簡(jiǎn)單粗暴且可讀性爆表呀！筆者會(huì)在接下來(lái)的系列文章中詳細(xì)介紹JSDuck的所有技術(shù)，并且最后會(huì)將筆者公司在JSDuck中前端框架的實(shí)踐以案例的形式分享給大家，敬請(qǐng)期待哦！
文章版權(quán)歸作者所有，未經(jīng)允許請(qǐng)勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請(qǐng)注明本文地址：http://systransis.cn/yun/90725.html
摘要：語(yǔ)法父類(lèi)名表示當(dāng)前類(lèi)繼承于哪個(gè)類(lèi)的標(biāo)簽。成員標(biāo)簽成員標(biāo)簽作用于類(lèi)中的配置屬性函數(shù)事件。表明可被子類(lèi)繼承，和一起使用。示例獲取圓的面積圓的半徑面積值作用于函數(shù)，表明函數(shù)的標(biāo)簽。作用于函數(shù)，表明構(gòu)造函數(shù)參數(shù)的標(biāo)簽，用法同。 字?jǐn)?shù)：3692字 閱讀時(shí)間：15分鐘 前言 ? 首先，咱們有一個(gè)前提，JSDuck對(duì)我們而言只是一個(gè)便于API查看的文檔化工具。因此，只要它能夠滿(mǎn)足我們文...
摘要：本文比較了種較為主流的注釋文檔生成工具。應(yīng)該說(shuō)是非常適合開(kāi)源項(xiàng)目多個(gè)作者共同維護(hù)的一個(gè)文檔工具。最后我選擇了作為文檔生成的工具。為了支持多種語(yǔ)言，它僅對(duì)注釋塊內(nèi)部的內(nèi)容進(jìn)行解析。 最近隨著寫(xiě)Node以及獨(dú)立的CommonJS模塊越來(lái)越多，我發(fā)現(xiàn)有一份好的文檔不僅可以幫助自己在應(yīng)用這些接口的時(shí)候不至于迷糊，而且對(duì)于共同開(kāi)發(fā)的情況下，能夠省去大量團(tuán)隊(duì)的交流和Debug的時(shí)間。 本文比較了...
摘要：我們先聲明了類(lèi)，在類(lèi)的注釋上添加標(biāo)簽表示靜態(tài)類(lèi)。靜態(tài)類(lèi)中包含一個(gè)方法，實(shí)現(xiàn)了一個(gè)簡(jiǎn)單的擴(kuò)展功能，后面類(lèi)的繼承需要用到這個(gè)接口。這里需要注意，靜態(tài)類(lèi)中，所有的成員也都是靜態(tài)的。 字?jǐn)?shù)：2543 閱讀時(shí)間：15分鐘 前言 ? 上一篇文章我們講述了JSDuck的詳細(xì)用法。那么，本文筆者就以實(shí)例為基礎(chǔ)，和大家一起，從零開(kāi)始，搭建一個(gè)簡(jiǎn)單的API文檔——我們的第一個(gè)API文檔V0.0.1。...
摘要：融合思路解決這個(gè)問(wèn)題，有兩種思路。給我們帶來(lái)了以下新成員模塊服務(wù)指令篩選器和控制器。與其他類(lèi)是通過(guò)類(lèi)的名稱(chēng)區(qū)分的，名稱(chēng)統(tǒng)一以結(jié)尾。這種處理方式是一種折中方案，如果想要更加規(guī)范優(yōu)雅的話(huà)，建議使用自定義標(biāo)簽來(lái)解決。 字?jǐn)?shù)：1568 閱讀時(shí)間：10分鐘 前言 ??前面，我們以一個(gè)實(shí)戰(zhàn)案例來(lái)詳細(xì)說(shuō)明了如何在實(shí)際開(kāi)發(fā)中使用JSDuck工具。但是，并不是所有的時(shí)候，代碼的封裝方式都受我們控制的。...
摘要：背景當(dāng)知道要上傳的視頻資料從條變成條時(shí)，我就明白，絕對(duì)不能再人工處理了。 背景 當(dāng)知道要上傳的視頻資料從20條變成100條時(shí)，我就明白，絕對(duì)不能再人工處理了。他們總是想當(dāng)然的認(rèn)為，錄入一條數(shù)據(jù)需要1分鐘，那錄入20條數(shù)據(jù)就是20分鐘，錄入100條數(shù)據(jù)，不就是100分鐘嗎？我有時(shí)候，真的很想問(wèn)問(wèn)他們，沒(méi)有考慮過(guò)人是會(huì)犯錯(cuò)的嗎？數(shù)據(jù)越多，出錯(cuò)的可能就越大；但是數(shù)據(jù)本身，又是不允許出現(xiàn)紕漏的...
閱讀 3670·2021-09-22 15:15
閱讀 3572·2021-08-12 13:24
閱讀 1319·2019-08-30 15:53
閱讀 1830·2019-08-30 15:43
閱讀 1191·2019-08-29 17:04
閱讀 2802·2019-08-29 15:08
閱讀 1594·2019-08-29 13:13
閱讀 3093·2019-08-29 11:06
