mirror of
https://github.com/danog/sass-site.git
synced 2024-12-15 02:47:36 +01:00
142 lines
5.1 KiB
Plaintext
142 lines
5.1 KiB
Plaintext
---
|
|
title: Comments
|
|
introduction: >
|
|
The way Sass comments work differs substantially between SCSS and the indented
|
|
syntax. Both syntaxes support two types of comments: comments defined using
|
|
`/* */` that are (usually) compiled to CSS, and comments defined using `//`
|
|
that are not.
|
|
---
|
|
|
|
{% markdown %}
|
|
## In SCSS
|
|
|
|
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.
|
|
|
|
**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.
|
|
|
|
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.
|
|
|
|
[statement]: /documentation/syntax/structure#statements
|
|
[interpolation]: /documentation/interpolation
|
|
[compressed mode]: /documentation/cli/dart-sass#style
|
|
{% endmarkdown %}
|
|
|
|
{% codeExample 'scss-comment', true, 'scss' %}
|
|
// 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;
|
|
}
|
|
{% endcodeExample %}
|
|
|
|
{% markdown %}
|
|
## In Sass
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
[interpolation]: /documentation/interpolation
|
|
[expressions]: /documentation/syntax/structure#expressions
|
|
{% endmarkdown %}
|
|
|
|
{% codeExample 'sass-comment', true, 'sass' %}
|
|
// 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
|
|
{% endcodeExample %}
|
|
|
|
{% markdown %}
|
|
## Documentation Comments
|
|
|
|
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][susy]'s documentation to see it in action!
|
|
|
|
[mixins]: /documentation/at-rules/mixin
|
|
[functions]: /documentation/at-rules/function
|
|
[variables]: /documentation/variables
|
|
[placeholder selectors]: /documentation/style-rules/placeholder-selectors
|
|
[SassDoc]: http://sassdoc.com
|
|
[susy]: http://oddbird.net/susy/docs/index.html
|
|
|
|
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.
|
|
|
|
[Markdown]: https://www.markdownguide.org/getting-started
|
|
[annotations]: http://sassdoc.com/annotations/
|
|
{% endmarkdown %}
|
|
|
|
{% codeExample 'documentation-comment' %}
|
|
/// 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;
|
|
}
|
|
===
|
|
/// 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
|
|
{% endcodeExample %}
|