SassDoc 詳細介紹與最佳實踐

SassDoc 是一款專門爲 Sass 代碼生成註釋的工具，經過 SassDoc，開發者能夠經過相似 JSDoc 的方式在 Sass 代碼上添加註釋，而後直接用命令生成文檔。最近在處理團隊框架 QMUI Web 時，遇到了須要爲大量 Sass 方法寫文檔的問題，所以研究了這個工具，本文將會詳細說明 SassDoc 的使用方法以及其中的最佳實踐。

基本使用

在 Sass 中，可使用多行註釋 /* xxxx */ 和單行註釋 // xxxx 兩種註釋方法。如文章開頭所述，SassDoc 是使用相似 JSDoc 的方式，即在代碼中經過註釋編寫文檔內容的方式生成文檔，所以 SassDoc 有特定的註釋語法：

/// 跨瀏覽器的漸變背景，垂直漸變，自上而下
///
/// @group 外觀
/// @name gradient_vertical
/// @param {Color} $start-color [#555] - 漸變的開始顏色
/// @param {Color} $end-color [#333] - 漸變的結束顏色
/// @param {Number} $start-percent [0%] - 漸變的開始位置，須要以百分號爲單位
/// @param {Number} $end-percent [100%] - 漸變的結束位置，須要以百分號爲單位
@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
}複製代碼

總結以下：

• 使用 /// 做爲 SassDoc 的註釋標識（舊版的 SassDoc 中，使用的是 Sass 的註釋方式，但這樣這些註釋也會被輸出到 CSS 代碼中，所以最新版的 SassDoc 選擇從新定義一個 /// 做爲專屬的註釋方式）
• /// 中的第一行沒有任何標記的文字會被看成 Sass 方法的描述
• 帶有 @name，@param 這類標記的會看成對應的註釋屬性，完整的標記列表能夠參考 sassdoc.com/annotations…

按照以上的方法，在 Sass 代碼上寫好了須要的註釋，接下來就應該輸出文檔了。輸出文檔首先要安裝 SassDoc 工具：

npm install sassdoc -g複製代碼

而後對須要生成文檔的 Sass 文件執行以下命令：

sassdoc sassFileName複製代碼

例如：對 _compatible.scss 執行上面的操做，會直接生成以下的文檔頁面：

如上圖各個方法已經根據註釋的內容輸出對應的文檔，而且文檔的樣式也很完善。至此，就是 SassDoc 的基本使用。

進階使用

使用非默認主題以及其餘選項

若是對默認的樣式不滿意，也可使用官網提供的其餘主題，在介紹如何使用其餘主題時，先要介紹一下 SassDoc 的選項：

• dest SassDoc 的輸出目錄，默認爲 ./sassdoc
• exclude 排除某些 Sass 文件，可使用 * 通配符，類型爲數組
• package 類型爲 String 或 Object，該選項能夠告知 SassDoc 項目的標題，版本號等信息，默認值爲 ./package.json
• theme 文檔的主題，默認爲 default
• autofill 規定那些屬性須要儘可能自動補全，默認爲 ["requires", "throws", "content"]
• groups 該方法的分組，文檔中會根據把同一個分組的方法歸類到一塊兒展現，默認爲 { undefined: "general" }
• no-update-notifier 在使用 SassDoc 時（例如執行輸出文檔的命令），若是當前的 SassDoc 不是最新版本，會有輸出提示，這個選項能夠控制取消這個提示，默認爲 false
• verbose SassDoc 默認不會輸出各個文檔的生成進度，若是須要能夠把這個選項設置爲 true
• strict 嚴格模式，默認爲 false，開啓後則使用一些廢棄語法會報錯（例如上面提到的舊版中可使用的多行註釋）

能夠看出，若是但願使用其餘主題，只須要下載對應的主題，而且在 theme 這個選項中進行配置便可，官方的其餘主題列表。

文件級註解

SassDoc 提供了一個文件級註解的功能，文件級註解與上面的普通註解類似，可是並非書寫在每一個方法之上，而是寫在文件的開頭，它做用是當方法的註解缺乏某些屬性時，會自動把文件級註解看成缺省值使用。

例如在 _calculate.scss 中，方法的註解中都沒有寫 group 這個屬性，但在文件級註解中有 group 屬性，後續生成的文檔都會以文件級註解中的 group 值看成自身的值。

代碼：

////
/// 輔助數值計算的工具方法
/// @author Kayo 
/// @group 數值計算 
/// @date 2015-08-23
////

/// 獲取 CSS 長度值屬性（例如：margin，padding，border-width 等）在某個方向的值
///
/// @name getLengthDirectionValue
/// @param {String} $property - 記錄着長度值的 SASS 變量 
/// @param {String} $direction - 須要獲取的方向，可選值爲 top，right，bottom，left，horizontal，vertical，其中 horizontal 和 vertical 分別須要長度值的左右或上下方向值相等，不然會報 Warning。
/// @example
///   // UI 界面的一致性每每要求類似外觀的組件保持距離、顏色等元素統一，例如：
///   // 搜索框和普通輸入框分開兩種結構處理，但但願搜索框的搜索 icon 距離左邊的空白與
///   // 普通輸入框光標距離左邊的空白保持一致，就須要獲取普通輸入框的 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) {
  ...
}複製代碼

效果：

最佳實踐

徹底自定義外觀

若是你不喜歡 SassDoc 提供的主題，或者自己的文檔有一整套樣式（例如上面提到的框架有本身的完整官網，所以 Sass 方法的文檔也須要配合官網的風格），那麼你就須要徹底自定義樣式。對開發者來講，經常使用的思路應該是把 Sass 代碼中的註釋輸出爲特定格式，例如 JSON，而後頁面中經過讀取這些數據輸出 HTML。

SassDoc 中也提供了一些相關的接口，第一步是把指定的 Sass 文件讀取出裏面的註解，並輸出數組，在此以前，你須要創建一個腳手架，方便你調用這個任務，持續地更新你的文檔，例如使用 Gulp，首先在本地目錄安裝 SassDoc：

npm install sassdoc --save-dev複製代碼

而後創建一個 Gulp 的 Task：

gulp.task('readToolMethod', false, function(){
  var sassdoc = require('sassdoc');

  sassdoc.parse([
    './qmui/helper/mixin/'
  ], {verbose: true})
  .then(function (_data) {
    // 文檔的數據
    console.log(_data);
  });
});複製代碼

能夠看到，會輸出數組格式的數據，並把每一個方法做爲一個 Object，Object 中包含了各個註解屬性及其屬性值：

接下來，你就能夠根據這個數據拼接 HTML 了。

數據分組

SassDoc 中輸出的數組數據並無按不一樣 Group 把方法歸類到不一樣的數組中，但在拼接 HTML 時，咱們通常須要把方法按 group 歸類到不一樣的數組中，方便遍歷。這裏給出一個方法，把剛剛的數組按 group 拆分紅二維數組：

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 把數組從新整理成二維數組
      var _result = [],
          _currentGroup = null,
          _currentGroupArray = null;
      for (var _i = 0; _i < _data.length; _i++) {
        var _item = _data[_i];
        // 因爲 IE8- 下 default 爲屬性的保留關鍵字，會引發錯誤，所以這裏要把參數中這個 default 的 key 從數據裏更名
        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();

      // 準備把數組寫入到指定文件中
      var _outputPath = './qmui_tools.json';

      // 寫入文件
      fs.writeFileSync(_outputPath, 'var comments = ' + JSON.stringify(_result), 'utf8');
    }
  });
});複製代碼

上面演示瞭如何把數組按 group 拆分爲二維數組，並以 JSON 格式寫入到文件中，方便拼接 HTML。須要注意的是，@param 這個註解中有一個 default 屬性，表明參數的默認值，所以生成 JSON 後會產生一個 default 屬性，在 IE8- 下，default 爲屬性的保留關鍵字，直接使用會引發錯誤，所以這裏要把參數中這個 default 的 key 從數據裏重命名，避免發生這種錯誤。

從新拼接方法體

在書寫文檔時，通常須要列出方法體（即完整的方法聲明），例如：

SassDoc 輸出的數據中自己不包含方法體，可是提供了組成方法體須要的數據，下面的方法能夠利用一個 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 += ', 複製代碼

__JJ_LT_JJ__/span__JJ_GT_JJ__; } __JJ_LT_JJ__span class="hljs-keyword"__JJ_GT_JJ__else__JJ_LT_JJ__/span__JJ_GT_JJ__ { result += __JJ_LT_JJ__span class="hljs-string"__JJ_GT_JJ__'__JJ_LT_JJ__/span__JJ_GT_JJ__; } result += paraItem.name; __JJ_LT_JJ__span class="hljs-keyword"__JJ_GT_JJ__if__JJ_LT_JJ__/span__JJ_GT_JJ__ (paraItem.defaultValue) { result = result + __JJ_LT_JJ__span class="hljs-string"__JJ_GT_JJ__': '__JJ_LT_JJ__/span__JJ_GT_JJ__ + paraItem.defaultValue; } } result += __JJ_LT_JJ__span class="hljs-string"__JJ_GT_JJ__')'__JJ_LT_JJ__/span__JJ_GT_JJ__; } result += __JJ_LT_JJ__span class="hljs-string"__JJ_GT_JJ__' { ... }'__JJ_LT_JJ__/span__JJ_GT_JJ__; __JJ_LT_JJ__span class="hljs-keyword"__JJ_GT_JJ__return__JJ_LT_JJ__/span__JJ_GT_JJ__ result; };

SassSDocMeister

最後推薦一款官方的工具—— SassSDocMeister，這個工具能夠在線預覽 SassDoc 註解的效果，對於剛接觸 SassDoc 的用戶來講會比較方便。

完整的 Demo 請參考 QMUI Web 和 QMUI Web Demo，若是你以爲這篇文章對你有幫助，歡迎 Star。