注释

SCSS 和缩进语法之间的 Sass 注释工作方式有很大不同。两种语法都支持两种类型的注释：使用 /* */ 定义的注释（通常）编译为 CSS，而使用 // 定义的注释则不然。

在 SCSS 中在 SCSS 中 permalink

¥In SCSS

SCSS 中的注释与 JavaScript 等其他语言中的注释类似。单行注释从 // 开始，一直到行尾。单行注释中的任何内容都不会以 CSS 形式发出；就 Sass 而言，它们可能不存在。它们也称为静默注释，因为它们不产生任何 CSS。

¥Comments in SCSS work similarly to comments in other languages like JavaScript. Single-line comments start with //, and go until the end of the line. Nothing in a single-line comment is emitted as CSS; as far as Sass is concerned, they may as well not exist. They’re also called silent comments, because they don’t produce any CSS.

多行注释从 /* 开始，到下一个 */ 结束。如果在允许 陈述 的地方写入多行注释，则会将其编译为 CSS 注释。与无声注释相比，它们也被称为响亮注释。编译为 CSS 的多行注释可能包含 插值法，它将在编译注释之前进行评估。

¥Multi-line comments start with /* and end at the next */. If a multi-line comment is written somewhere that a statement is allowed, it’s compiled to a CSS comment. They’re also called loud comment, by contrast with silent comments. A multi-line comment that’s compiled to CSS may contain interpolation, which will be evaluated before the comment is compiled.

默认情况下，压缩模式 中的多行注释将从编译的 CSS 中删除。但是，如果注释以 /*! 开头，它将始终包含在 CSS 输出中。

¥By default, multi-line comments will be stripped from the compiled CSS in compressed mode. If a comment begins with /*!, though, it will always be included in the CSS output.

Playground

SCSS Syntax

// This comment won't be included in the CSS.

/* But this comment will, except in compressed mode. */

/* It can also contain interpolation:

* 1 + 1 = #{1 + 1} */

/*! This comment will be included even in compressed mode. */

p /* Multi-line comments can be written anywhere

  * whitespace is allowed. */ .sans {
  font: Helvetica, // So can single-line comments.
        sans-serif;
}

CSS Output

/* But this comment will, except in compressed mode. */
/* It can also contain interpolation:

* 1 + 1 = 2 */
/*! This comment will be included even in compressed mode. */
p .sans {
  font: Helvetica, sans-serif;
}

在 Sass 中在 Sass 中 permalink

¥In Sass

缩进语法中的注释工作方式略有不同：它们是基于缩进的，就像语法的其余部分一样。与 SCSS 一样，用 // 编写的无声注释永远不会作为 CSS 发出，但与 SCSS 不同的是，开头 // 下面缩进的所有内容也会被注释掉。

¥Comments in the indented syntax work a little differently: they’re indentation-based, just like the rest of the syntax. Like SCSS, silent comments written with // are never emitted as CSS, but unlike SCSS everything indented beneath the opening // is also commented out.

以 /* 开头的缩进语法注释与缩进的工作方式相同，只不过它们被编译为 CSS。由于注释的范围基于缩进，因此结束的 */ 是可选的。与 SCSS 一样，/* 注释可以包含 插值法 并且可以以 /*! 开头，以避免在压缩模式下被剥离。

¥Indented syntax comments that start with /* work with indentation the same way, except that they are compiled to CSS. Because the extent of the comment is based on indentation, the closing */ is optional. Also like SCSS, /* comments can contain interpolation and can start with /*! to avoid being stripped in compressed mode.

注释也可以在缩进语法中的 表达式 内使用。在本例中，它们的语法与 SCSS 中的语法完全相同。

¥Comments can also be used within expressions in the indented syntax. In this case, they have exactly the same syntax as they do in SCSS.

Playground

Sass Syntax

// This comment won't be included in the CSS.
  This is also commented out.

/* But this comment will, except in compressed mode.

/* It can also contain interpolation:
  1 + 1 = #{1 + 1}

/*! This comment will be included even in compressed mode.

p .sans
  font: Helvetica, /* Inline comments must be closed. */ sans-serif

CSS Output

/* But this comment will, except in compressed mode. */
/* It can also contain interpolation:
 * 1 + 1 = 2 */
/*! This comment will be included even in compressed mode. */
p .sans {
  font: Helvetica, sans-serif;
}

文档注释文档注释 permalink

¥Documentation Comments

使用 Sass 编写样式库时，你可以使用注释来记录库提供的 混入、函数、变量 和 占位符选择器 以及库本身。这些注释由 SassDoc 工具读取，该工具使用它们生成漂亮的文档。查看 Susy 网格引擎 的文档以了解其实际效果！

¥When writing style libraries using Sass, you can use comments to document the mixins, functions, variables, and placeholder selectors that your library provides, as well as the library itself. These comments are read by the SassDoc tool, which uses them to generate beautiful documentation. Check out the Susy grid engine’s documentation to see it in action!

文档注释是无声注释，在你正在记录的内容正上方用三个斜杠 (///) 书写。SassDoc 将注释中的文本解析为 Markdown，并支持许多有用的 注释 来对其进行详细描述。

¥Documentation comments are silent comments, written with three slashes (///) directly above the thing you’re documenting. SassDoc parses text in the comments as Markdown, and supports many useful annotations to describe it in detail.

Playground

SCSS Syntax

/// Computes an exponent.
///
/// @param {number} $base
///   The number to multiply by itself.
/// @param {integer (unitless)} $exponent
///   The number of `$base`s to multiply together.
/// @return {number} `$base` to the power of `$exponent`.
@function pow($base, $exponent) {
  $result: 1;
  @for $_ from 1 through $exponent {
    $result: $result * $base;
  }
  @return $result;
}
Playground

Sass Syntax

/// Computes an exponent.
///
/// @param {number} $base
///   The number to multiply by itself.
/// @param {integer (unitless)} $exponent
///   The number of `$base`s to multiply together.
/// @return {number} `$base` to the power of `$exponent`.
@function pow($base, $exponent)
  $result: 1
  @for $_ from 1 through $exponent
    $result: $result * $base

  @return $result