SassDoc 详细介绍与最佳实践

时间 2019-11-17

标签 sassdoc 详细介绍最佳实践繁體版

原文原文链接

SassDoc 是一款专门为 Sass 代码生成注释的工具，经过 SassDoc，开发者能够经过相似 JSDoc 的方式在 Sass 代码上添加注释，而后直接用命令生成文档。最近在处理团队框架 QMUI Web 时，遇到了须要为大量 Sass 方法写文档的问题，所以研究了这个工具，本文将会详细说明 SassDoc 的使用方法以及其中的最佳实践。javascript

基本使用

在 Sass 中，可使用多行注释 /* xxxx */ 和单行注释 // xxxx 两种注释方法。如文章开头所述，SassDoc 是使用相似 JSDoc 的方式，即在代码中经过注释编写文档内容的方式生成文档，所以 SassDoc 有特定的注释语法：css

/// 跨浏览器的渐变背景，垂直渐变，自上而下
///
/// @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
}复制代码

总结以下：java

使用 /// 做为 SassDoc 的注释标识（旧版的 SassDoc 中，使用的是 Sass 的注释方式，但这样这些注释也会被输出到 CSS 代码中，所以最新版的 SassDoc 选择从新定义一个 /// 做为专属的注释方式）
/// 中的第一行没有任何标记的文字会被看成 Sass 方法的描述
带有 @name，@param 这类标记的会看成对应的注释属性，完整的标记列表能够参考 sassdoc.com/annotations…

按照以上的方法，在 Sass 代码上写好了须要的注释，接下来就应该输出文档了。输出文档首先要安装 SassDoc 工具：git

npm install sassdoc -g复制代码

而后对须要生成文档的 Sass 文件执行以下命令：github

sassdoc sassFileName复制代码

例如：对 _compatible.scss 执行上面的操做，会直接生成以下的文档页面：web

如上图各个方法已经根据注释的内容输出对应的文档，而且文档的样式也很完善。至此，就是 SassDoc 的基本使用。npm

进阶使用

使用非默认主题以及其余选项

若是对默认的样式不满意，也可使用官网提供的其余主题，在介绍如何使用其余主题时，先要介绍一下 SassDoc 的选项：json

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 这个选项中进行配置便可，官方的其余主题列表。gulp

文件级注解

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。