每一個(gè)旨在代碼庫(kù)中復(fù)用的變量、函數(shù)、混合宏和占位符，都應(yīng)該使用SassDoc?記錄下來(lái)作為全部 API 的一部分。

/// Vertical rhythm baseline used all over the code base.
/// @type Length
$vertical-rhythm-baseline: 1.5rem;

需要三個(gè)反斜杠(/)

SassDoc 主要有兩個(gè)作用：

• 作為公有或私有 API 的一部分，在所有的地方使用一個(gè)注釋系統(tǒng)強(qiáng)制標(biāo)準(zhǔn)化注釋。
• 通過(guò)使用任意的 SassDoc 終端(CLI tool, Grunt, Gulp, Broccoli, Node…)，能夠生成 API 文檔的 HTML 版本。

本文檔由 SassDoc 生成

這里有一個(gè)深入整合 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;
}

擴(kuò)展閱讀

• SassDoc
• SassDoc: a Documentation Tool for Sass