每一个旨在代码库中复用的变量、函数、混合宏和占位符，都应该使用[SassDoc](http://sassdoc.com/) 记录下来作为全部 API 的一部分。 ~~~ /// Vertical rhythm baseline used all over the code base. /// @type Length $vertical-rhythm-baseline: 1.5rem; ~~~ 需要三个反斜杠(`/`) SassDoc 主要有两个作用： * 作为公有或私有 API 的一部分，在所有的地方使用一个注释系统强制标准化注释。 * 通过使用任意的 SassDoc 终端(CLI tool, Grunt, Gulp, Broccoli, Node…)，能够生成 API 文档的 HTML 版本。 本文档由 SassDoc 生成 这里有一个深入整合 SassDoc 生成文档的例子： ~~~ /// Mixin helping defining both `width` and `height` simultaneously. /// /// @author Hugo Giraudel /// /// @access public /// /// @param {Length} $width - Element’s `width` /// @param {Length} $height ($width) - Element’s `height` /// /// @example scss - Usage /// .foo { /// @include size(10em); /// } /// /// .bar { /// @include size(100%, 10em); /// } /// /// @example css - CSS output /// .foo { /// width: 10em; /// height: 10em; /// } /// /// .bar { /// width: 100%; /// height: 10em; /// } @mixin size($width, $height: $width) { width: $width; height: $height; } ~~~ ## 扩展阅读 * [SassDoc](http://sassdoc.com/) * [SassDoc: a Documentation Tool for Sass](http://www.sitepoint.com/sassdoc-documentation-tool-sass/)