SassDoc 是一款專門(mén)為 Sass 代碼生成注釋的工具，通過(guò) SassDoc淹办，開(kāi)發(fā)者可以通過(guò)類似 JSDoc 的方式在 Sass 代碼上添加注釋印荔，然后直接用命令生成文檔。最近在處理團(tuán)隊(duì)框架 QMUI Web 時(shí)从撼，遇到了需要為大量 Sass 方法寫(xiě)文檔的問(wèn)題州弟，因此研究了這個(gè)工具，本文將會(huì)詳細(xì)說(shuō)明 SassDoc 的使用方法以及其中的最佳實(shí)踐低零。
基本使用
在 Sass 中婆翔，可以使用多行注釋 /* xxxx */ 和單行注釋 // xxxx 兩種注釋方法。如文章開(kāi)頭所述掏婶，SassDoc 是使用類似 JSDoc 的方式啃奴，即在代碼中通過(guò)注釋編寫(xiě)文檔內(nèi)容的方式生成文檔，因此 SassDoc 有特定的注釋語(yǔ)法：
/// 跨瀏覽器的漸變背景雄妥，垂直漸變最蕾，自上而下
///
/// @group 外觀
/// @name gradient_vertical
/// @param {Color} $start-color [#555] - 漸變的開(kāi)始顏色
/// @param {Color} $end-color [#333] - 漸變的結(jié)束顏色
/// @param {Number} $start-percent [0%] - 漸變的開(kāi)始位置，需要以百分號(hào)為單位
/// @param {Number} $end-percent [100%] - 漸變的結(jié)束位置老厌，需要以百分號(hào)為單位
@mixin gradient_vertical($start-color: #555, $end-color: #333, $start-percent: 0%, $end-percent: 100%){
background-image: -webkit-gradient(linear, left top, left bottom, color-stop($start-percent, $start-color), color-stop($end-percent, $end-color)); // Safari 4-5, Chrome 1-9
background-image: -webkit-linear-gradient(top, $start-color $start-percent, $end-color $end-percent); // Safari 5.1-6, Chrome 10+
background-image: -moz-linear-gradient(top, $start-color $start-percent, $end-color $end-percent); // Firefox 3.6+
background-image: -o-linear-gradient(top, $start-color $start-percent, $end-color $end-percent); // Opera 12
background-image: linear-gradient(to bottom, $start-color $start-percent, $end-color $end-percent); // Standard, IE10, Firefox 16+, Opera 12.10+, Safari 7+, Chrome 26+
background-repeat: repeat-x;
filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#{ie-hex-str($start-color)}', endColorstr='#{ie-hex-str($end-color)}', GradientType=0); // IE9 and down
}
總結(jié)如下：
- 使用
///作為 SassDoc 的注釋標(biāo)識(shí)（舊版的 SassDoc 中瘟则，使用的是 Sass 的注釋方式，但這樣這些注釋也會(huì)被輸出到 CSS 代碼中枝秤，因此最新版的 SassDoc 選擇重新定義一個(gè)///作為專屬的注釋方式） -
///中的第一行沒(méi)有任何標(biāo)記的文字會(huì)被當(dāng)作 Sass 方法的描述 - 帶有
@name醋拧，@param這類標(biāo)記的會(huì)當(dāng)作對(duì)應(yīng)的注釋屬性，完整的標(biāo)記列表可以參考 http://sassdoc.com/annotations/
按照以上的方法，在 Sass 代碼上寫(xiě)好了需要的注釋趁仙，接下來(lái)就應(yīng)該輸出文檔了洪添。輸出文檔首先要安裝 SassDoc 工具：
npm install sassdoc -g
然后對(duì)需要生成文檔的 Sass 文件執(zhí)行如下命令：
sassdoc sassFileName
例如：對(duì) _compatible.scss 執(zhí)行上面的操作，會(huì)直接生成如下的文檔頁(yè)面：
如上圖各個(gè)方法已經(jīng)根據(jù)注釋的內(nèi)容輸出對(duì)應(yīng)的文檔雀费，并且文檔的樣式也很完善干奢。至此，就是 SassDoc 的基本使用盏袄。
進(jìn)階使用
使用非默認(rèn)主題以及其他選項(xiàng)
如果對(duì)默認(rèn)的樣式不滿意忿峻，也可以使用官網(wǎng)提供的其他主題，在介紹如何使用其他主題時(shí)辕羽，先要介紹一下 SassDoc 的選項(xiàng)：
-
dest SassDoc 的輸出目錄逛尚，默認(rèn)為
./sassdoc - exclude 排除某些 Sass 文件，可以使用 * 通配符刁愿，類型為數(shù)組
-
package 類型為 String 或 Object绰寞，該選項(xiàng)可以告知 SassDoc 項(xiàng)目的標(biāo)題，版本號(hào)等信息铣口，默認(rèn)值為
./package.json - theme 文檔的主題滤钱，默認(rèn)為 default
-
autofill 規(guī)定那些屬性需要盡量自動(dòng)補(bǔ)全，默認(rèn)為
["requires", "throws", "content"] -
groups 該方法的分組脑题，文檔中會(huì)根據(jù)把同一個(gè)分組的方法歸類到一起展示件缸，默認(rèn)為
{ undefined: "general" } -
no-update-notifier 在使用 SassDoc 時(shí)（例如執(zhí)行輸出文檔的命令），如果當(dāng)前的 SassDoc 不是最新版本叔遂，會(huì)有輸出提示他炊，這個(gè)選項(xiàng)可以控制取消這個(gè)提示，默認(rèn)為
false -
verbose SassDoc 默認(rèn)不會(huì)輸出各個(gè)文檔的生成進(jìn)度已艰，如果需要可以把這個(gè)選項(xiàng)設(shè)置為
true -
strict 嚴(yán)格模式痊末，默認(rèn)為
false，開(kāi)啟后則使用一些廢棄語(yǔ)法會(huì)報(bào)錯(cuò)（例如上面提到的舊版中可以使用的多行注釋）
可以看出旗芬，如果希望使用其他主題舌胶，只需要下載對(duì)應(yīng)的主題，并且在 theme 這個(gè)選項(xiàng)中進(jìn)行配置即可疮丛，官方的其他主題列表幔嫂。
文件級(jí)注解
SassDoc 提供了一個(gè)文件級(jí)注解的功能，文件級(jí)注解與上面的普通注解相似誊薄，但是并不是書(shū)寫(xiě)在每個(gè)方法之上履恩，而是寫(xiě)在文件的開(kāi)頭，它作用是當(dāng)方法的注解缺少某些屬性時(shí)呢蔫，會(huì)自動(dòng)把文件級(jí)注解當(dāng)作缺省值使用切心。
例如在 _calculate.scss 中飒筑，方法的注解中都沒(méi)有寫(xiě) group 這個(gè)屬性，但在文件級(jí)注解中有 group 屬性绽昏，后續(xù)生成的文檔都會(huì)以文件級(jí)注解中的 group 值當(dāng)作自身的值协屡。
代碼：
////
/// 輔助數(shù)值計(jì)算的工具方法
/// @author Kayo
/// @group 數(shù)值計(jì)算
/// @date 2015-08-23
////
/// 獲取 CSS 長(zhǎng)度值屬性（例如：margin，padding全谤，border-width 等）在某個(gè)方向的值
///
/// @name getLengthDirectionValue
/// @param {String} $property - 記錄著長(zhǎng)度值的 SASS 變量
/// @param {String} $direction - 需要獲取的方向肤晓，可選值為 top，right认然，bottom补憾，left，horizontal卷员，vertical盈匾，其中 horizontal 和 vertical 分別需要長(zhǎng)度值的左右或上下方向值相等，否則會(huì)報(bào) Warning毕骡。
/// @example
/// // UI 界面的一致性往往要求相似外觀的組件保持距離削饵、顏色等元素統(tǒng)一，例如：
/// // 搜索框和普通輸入框分開(kāi)兩種結(jié)構(gòu)處理未巫，但希望搜索框的搜索 icon 距離左邊的空白與
/// // 普通輸入框光標(biāo)距離左邊的空白保持一致葵孤，就需要獲取普通輸入框的 padding-left
/// $textField_padding: 4px 5px;
/// .dm_textField {
/// padding: $textField_padding;
/// }
/// .dm_searchInput {
/// position: relative;
/// ...
/// }
/// .dm_searchInput_icon {
/// position: absolute;
/// left: getLengthDirectionValue($textField_padding, left);
/// ...
/// }
@function getLengthDirectionValue($property, $direction) {
...
}
效果：
最佳實(shí)踐
完全自定義外觀
如果你不喜歡 SassDoc 提供的主題，或者本身的文檔有一整套樣式（例如上面提到的框架有自己的完整官網(wǎng)橱赠，因此 Sass 方法的文檔也需要配合官網(wǎng)的風(fēng)格），那么你就需要完全自定義樣式箫津。對(duì)開(kāi)發(fā)者來(lái)說(shuō)狭姨，常用的思路應(yīng)該是把 Sass 代碼中的注釋輸出為特定格式，例如 JSON苏遥，然后頁(yè)面中通過(guò)讀取這些數(shù)據(jù)輸出 HTML饼拍。
SassDoc 中也提供了一些相關(guān)的接口，第一步是把指定的 Sass 文件讀取出里面的注解田炭，并輸出數(shù)組师抄，在此之前，你需要建立一個(gè)腳手架教硫，方便你調(diào)用這個(gè)任務(wù)叨吮，持續(xù)地更新你的文檔，例如使用 Gulp瞬矩，首先在本地目錄安裝 SassDoc：
npm install sassdoc --save-dev
然后建立一個(gè) Gulp 的 Task：
gulp.task('readToolMethod', false, function(){
var sassdoc = require('sassdoc');
sassdoc.parse([
'./qmui/helper/mixin/'
], {verbose: true})
.then(function (_data) {
// 文檔的數(shù)據(jù)
console.log(_data);
});
});
可以看到茶鉴，會(huì)輸出數(shù)組格式的數(shù)據(jù)，并把每個(gè)方法作為一個(gè) Object景用，Object 中包含了各個(gè)注解屬性及其屬性值：
接下來(lái)涵叮，你就可以根據(jù)這個(gè)數(shù)據(jù)拼接 HTML 了。
數(shù)據(jù)分組
SassDoc 中輸出的數(shù)組數(shù)據(jù)并沒(méi)有按不同 Group 把方法歸類到不同的數(shù)組中，但在拼接 HTML 時(shí)割粮，我們一般需要把方法按 group 歸類到不同的數(shù)組中盾碗，方便遍歷。這里給出一個(gè)方法舀瓢，把剛剛的數(shù)組按 group 拆分成二維數(shù)組：
gulp.task('readToolMethod', false, function(){
var fs = require('fs'),
sassdoc = require('sassdoc'),
_ = require('lodash');
sassdoc.parse([
'./qmui/helper/mixin/'
], {verbose: true})
.then(function (_data) {
if (_data.length > 0) {
// 按 group 把數(shù)組重新整理成二維數(shù)組
var _result = [],
_currentGroup = null,
_currentGroupArray = null;
for (var _i = 0; _i < _data.length; _i++) {
var _item = _data[_i];
// 由于 IE8- 下 default 為屬性的保留關(guān)鍵字廷雅，會(huì)引起錯(cuò)誤，因此這里要把參數(shù)中這個(gè) default 的 key 從數(shù)據(jù)里改名
if (_item.parameter) {
for (var _j = 0; _j < _item.parameter.length; _j++) {
var _paraItem = _item.parameter[_j];
if (_paraItem.hasOwnProperty('default')) {
_paraItem['defaultValue'] = _paraItem['default'];
delete _paraItem['default'];
}
}
}
if (!_.isEqual(_item.group, _currentGroup)) {
_currentGroup = _item.group;
_currentGroupArray = [];
_result.push(_currentGroupArray);
} else {
_currentGroupArray = _result[_result.length - 1];
}
_currentGroupArray.push(_item);
}
_result.reverse();
// 準(zhǔn)備把數(shù)組寫(xiě)入到指定文件中
var _outputPath = './qmui_tools.json';
// 寫(xiě)入文件
fs.writeFileSync(_outputPath, 'var comments = ' + JSON.stringify(_result), 'utf8');
}
});
});
上面演示了如何把數(shù)組按 group 拆分為二維數(shù)組氢伟，并以 JSON 格式寫(xiě)入到文件中榜轿，方便拼接 HTML。需要注意的是朵锣，@param 這個(gè)注解中有一個(gè) default 屬性谬盐，代表參數(shù)的默認(rèn)值，因此生成 JSON 后會(huì)產(chǎn)生一個(gè) default 屬性诚些，在 IE8- 下飞傀，default 為屬性的保留關(guān)鍵字，直接使用會(huì)引起錯(cuò)誤诬烹，因此這里要把參數(shù)中這個(gè) default 的 key 從數(shù)據(jù)里重命名砸烦，避免發(fā)生這種錯(cuò)誤。
重新拼接方法體
在書(shū)寫(xiě)文檔時(shí)绞吁，一般需要列出方法體（即完整的方法聲明）幢痘，例如：
SassDoc 輸出的數(shù)據(jù)中本身不包含方法體，但是提供了組成方法體需要的數(shù)據(jù)家破，下面的方法可以利用一個(gè) SassDoc 的 item 拼接處完整的方法體：
var makeCompleteMethodWithItem = function(item) {
var result = '',
itemType = null;
if (item.context.type === 'placeholder') {
itemType = '%';
} else {
itemType = item.context.type + ' ';
result = '@';
}
result = result + itemType + item.context.name;
if (item.parameter) {
result += '(';
var paraList = item.parameter;
for (var paraIndex = 0; paraIndex < paraList.length; paraIndex++) {
var paraItem = paraList[paraIndex];
if (paraIndex !== 0) {
result += ', $';
} else {
result += '$';
}
result += paraItem.name;
if (paraItem.defaultValue) {
result = result + ': ' + paraItem.defaultValue;
}
}
result += ')';
}
result += ' { ... }';
return result;
};
SassSDocMeister
最后推薦一款官方的工具—— SassSDocMeister颜说，這個(gè)工具可以在線預(yù)覽 SassDoc 注解的效果，對(duì)于剛接觸 SassDoc 的用戶來(lái)說(shuō)會(huì)比較方便汰聋。
完整的 Demo 請(qǐng)參考 QMUI Web 和 QMUI Web Demo门粪，如果你覺(jué)得這篇文章對(duì)你有幫助，歡迎 Star烹困。
