每一個旨在代碼庫中復用的變量、函數、混合宏和占位符，都應該使用[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/)