这篇文章中我们详细说明下开发Sass代码时, 可以书写的注释有哪些类型

通过SassDoc, 开发者可以像书写JSDoc一样编写Sass的注释代码, 然后通过命令快速生成API文档

SassDoc使用详情, 猛戳SassDoc传送门

原生的注释类型

多行注释

Example:

1
2
3
4
5
6
7
8
9
/* This is a variant
of a multi-line
comment. */

.selector {
   color: #fff;
   font-size: 16px;
   text-align: right;
}

注意：多行注释在编译后会被直接输出到CSS代码中

单行注释

Example 1:

1
2
3
4
5
6
7
// Styles for a selector.

.selector {
   color: #fff;
   font-size: 16px;
   text-align: right;
}

Example 2:

1
2
3
.example-rule {
 float: left; // Styles for LTR direction property.
}

注意：单行注释在编译环节将被过滤，不会输出到CSS代码中

SassDoc的注释

SassDoc规范的注释代码不希望被输出到CSS代码中，因此选择了升级版 的单行注释作为注释界定符

Example:

1
2
3
4
5
6
/// Here is the description
/// On several lines if you will
/// @author Author's name

/// @access private
/// @alias other-item

注意：3个斜杠追加一个空格 /// 作为一行注释的起始

SassDoc的文件级别注释

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
////
/// 这是一个文件级别的全局注释
/// 该文件内的所有Item都将被应用该注释的描述
/// @group API
/// @author gaofeng.gf
////

/// 该Item从文件级注释继承了
/// `@group API` 与 `@author gaofeng.gf` 两个注释项
@function dummy-function() {
  // ...
}

/// 该Item覆写了 `@author` 这个从全局继承的注释项
/// @author zhouyuan.yz
@mixin dummy-mixin {
  // ...
}

注意：4个斜杠追加一个空格 //// 作为文件级注释的『起始』与『结束』

数据类型

SassScript 支持7大数据类型

  • numbers (如 1.2, 13, 10px)
  • strings (如 “foo”, ‘bar’, baz)
  • colors (如 blue, #04a3f9, rgba(255, 0, 0, 0.5))
  • booleans (如 true, false)
  • nulls (如 null)
  • lists (以逗号或空格分隔，如 1.5em 1em 0 2em, Helvetica, Arial, sans-serif)
  • maps (如 (key1: value1, key2: value2))

在注释数据类型中分别对应：

  • Number
  • String
  • Color
  • Bool
  • Null
  • List
  • Map

注释项

注释声明 描述 别称 默认值 使用范围 补充说明
@access 定义功能块的访问类型 - public functions, mixins, placeholders, variables 为private类型时，sassdoc将在生成文档时忽略此功能块
@alias 描述该功能块是否是其他功能块的别称 - - functions, mixins, placeholders, variables -
@author 功能块开发者 - - functions, mixins, placeholders, variables -
@content 对@content指令的用法进行描述 - - mixins -
@deprecated 标识该功能模块已废弃 - - functions, mixins, placeholders, variables 可在描述项后面追加描述信息
@example 功能块使用示例 - - functions, mixins, placeholders, variables 1. 示例内容需要缩进;
2.@example（空格）后可追加需要高亮的语法，支持 css, scss, markup, javascript 四种语法 最佳实践
@group 该功能块所属的分组 - undefined functions, mixins, placeholders, variables 分组定义了功能块在文档中的展示方式
@ignore 声明该行注释将不会被生成文档条目 - - functions, mixins, placeholders, variables -
@link 链接 @source - functions, mixins, placeholders, variables 超链接（空格）后可追加链接标题
@name 自定义功能块在文档中的显示名 - item.context.name functions, mixins, placeholders, variables -
@output 对@mixin指令输出的内容进行描述 @outputs - mixins -
@parameter 对功能块的功能参数进行描述 @arg, @argument, @param - functions, mixins 1. 默认值可选
2.参数描述可选
3.如有多类型用竖线符号分隔 最佳实践
@property 记录映射maps类型变量的属性，使用’.’进行嵌套属性访问 @prop - variables 同@parameter
@require 对该功能块依赖其他功能块进行描述 @requires - functions, mixins, placeholders, variables -
@return 对函数的返回结果进行描述 @returns - functions 如有多类型用竖线符号分隔
@see 记录了与该功能块关联的功能块 - - functions, mixins, placeholders, variables -
@since 记录该功能块开始实现的版本号 - - functions, mixins, placeholders, variables 版本号（空格）后可追加版本描述
@throw 记录一个被功能块 @error 指令抛出的错误信息 @throws, @exception - functions, mixins, placeholders -
@todo 记录关于功能块的待做任务 - - functions, mixins, placeholders, variables -
@type 描述变量的类型 - - variables 如有多类型用竖线符号分隔

最佳实践

Variable

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
@charset "UTF-8";

////
/// 我是该文件的全局注释，对文件内的所有功能块均生效
///
/// @group Variable
/// @author jack.ma
////

/// 通用错误信息
/// @type String
$error-massege: "编译错误，请检查代码！";

/// 通用步长
/// @type Number
$step-number: 4;

/// 是否是开发版本
/// @type Bool
$is-dev: true;

/// 通用占位变量
/// @type Null
$placeholder: null;

/// 通用背景色
/// @type Color
$background-color: rgba(1, 2, 3, 0.6);

/// 媒体查询断点映射 - List类型
/// @type List
$breakpoint-list: (
  (small, null, 479px, 16px, 1.3),
  (medium, 480px, 959px, 18px, 1.414),
  (large, 960px, 1099px, 18px, 1.5),
  (xlarge, 1100px, null, 21px, 1.618)
  );

/// 媒体查询断点映射 - Map类型
/// @type Map
/// @property {String} breakpoint-map.small - 小屏幕断点
/// @property {String} breakpoint-map.medium - 中等屏幕断点
/// @property {String} breakpoint-map.large [1200px] - 大屏幕断点
$breakpoint-map: (
  small: 767px,
  medium: 992px,
  large: 1200px
);

Function

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
@charset "UTF-8";

////
/// 我是该文件的全局注释，对文件内的所有功能块均生效
///
/// @group Function
/// @author jack.ma
////

/// 检查一个值是否为合法的CSS长度
///
/// @since 1.0.1
/// @access public
/// @param {String} $value - 长度
/// @throw 当值为`1`时抛出错误
/// @return {Bool} 是否是长度
/// @todo 检查 CSS Next 中的长度
/// @link http://gitlab.alibaba-inc.com

@function is-length($value) {
  @warn "我是警告信息！不会导致编译失败";
  @debug "我是调试信息！不会导致编译失败";

  @if $value == 1 {
    @error "我是错误信息：数字1肯定不是参数，编译失败！";
  }

  @return type-of($value) != "null" and (str-slice($value + "", 1, 4) == "calc" /// 是calc函数来计算的长度
    or (type-of(index(auto inherit initial 0, $value)) == "number")
    or (type-of($value) == "number" and not(unitless($value))));
}

Mixin

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
@charset "UTF-8";

////
/// 我是该文件的全局注释，对文件内的所有功能块均生效
///
/// @group Mixin
/// @author jack.ma
////

/// 提供了快捷设置元素postion的方法，传入null参数可略过一个方位
///
///
/// @since 0.1.9
/// @group Mixin
///
/// @param {String} $position [relative] - CSS position属性值
/// @param {List} $coordinates [null null null null] - 上、右、下、左 四个边值，可以传入1 ~ 4个值
///
/// @output 输出定位属性值以及四个方位的距离
///
/// @example scss - 使用
///   .element {
///     @include position(absolute, 0 null null 10px);
///   }
///
/// @example css - 输出
///   .element {
///     position: absolute;
///     left: 10px;
///     top: 0;
///   }
/// @see {mixin} box
/// @require {function} is-length
/// @require {function} unpack
///
/// @ignore 我是将要被忽略的注释行信息

@mixin position($position: relative, $coordinates: null null null null) {

  /// 如果参数是数组
  @if type-of($position) == list {
    $coordinates: $position;
    $position: relative;
  }

  $coordinates: unpack($coordinates);

  $offsets: (
    top:    nth($coordinates, 1),
    right:  nth($coordinates, 2),
    bottom: nth($coordinates, 3),
    left:   nth($coordinates, 4)
  );

  position: $position;

  @each $offset, $value in $offsets {

    /// 如果是合法长度
    @if is-length($value) {
      #{$offset}: $value;
    }
  }
}

/// 媒体查询混入
///
/// @since 0.1.9
/// @group Mixin
/// @content 任意CSS样式
/// @access public
///
/// @param {String} $width - CSS宽度值
///
/// @example scss - 使用
///   .element {
///     color: #333;  
///     
///     @include media(320px) {
///       background: red;
///     }
///   }
///
/// @example css - 输出
///   .element {
///     color: #333;
///   }
///   
///   @media only screen and (max-width: 320px) {
///     .element {
///       background: red;
///     }
///   }

@mixin media($width) {
  @media only screen and (max-width: $width) {
    @content;
  }
}

.element {
  color: #333;  
  @include media(320px) {
    background: red;
  }
}

Placeholder

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
@charset "UTF-8";

////
/// 我是该文件的全局注释，对文件内的所有功能块均生效
///
/// @group Placeholder
/// @author jack.ma
////

/// 图标通用代码
///
/// @deprecated
/// @name common-icon
/// @example scss - 使用
///   .error-icon {
///     @extend %icon;
///     /* error specific styles... */
///   }
///   .info-icon {
///     @extend %icon;
///     /* info specific styles... */
///   }
///
/// @example css - 输出
///   .error-icon, .info-icon {
///     transition: background-color ease .2s;
///     margin: 0 .5em;
///   }
///
///   .error-icon {
///     /* error specific styles... */
///   }
///
///   .info-icon {
///     /* info specific styles... */
///   }
/// @todo 大版本迭代时去除
%icon {
  transition: background-color ease .2s;
  margin: 0 .5em;
}


详情查看 http://sassdoc.com/annotations/

本文地址： https://mrpeak.github.io/2016/01/28/sass-annotation/