<p>SCSS注释本身不生成文档，仅///开头的结构化注释配合SassDoc工具链才能生成API文档；/ /和//注释被完全忽略，且必须紧贴声明、位于入口文件依赖树内。</p>
直接上结论：SCSS 注释本身无法“自动生成文档”，所谓“结构化注释”只是为后续工具（如 sassdoc）提供可解析的元数据，关键在格式约定 + 工具链配合。不装插件、不跑命令，再规范的注释也只是一段文本。
SCSS 注释必须用 /// 开头才能被 sassdoc 解析
普通 /* */ 或 // 注释会被 sassdoc 完全忽略。只有以三个斜杠 /// 开头的行，且紧贴在变量、mixin、function 或占位符选择器上方时，才会被识别为文档注释块。
-
///后面建议空一格再写内容，避免解析失败 - 不能跨行写多个
///拼接 —— 必须是连续的、顶格的///行块 - 下面这个写法有效：
/// 定义主色调，用于按钮、链接等交互元素 /// @type color /// @group theme $primary-color: #409eff;
而下面这个无效（// 不识别）：
// 定义主色调 $primary-color: #409eff;
@group、@type、@param 这些标签不是可选的“补充说明”
它们是 sassdoc 的解析契约，漏掉或拼错会导致字段丢失或归类错误。比如 @group 决定组件在生成的 HTML 文档中归属哪个导航栏分组；@type 影响值类型提示是否显示；@param 缺失会让 mixin 的参数表为空。
立即学习“前端免费学习笔记（深入）”；
-
@group值建议用短横线分隔小写单词，如theme、layout-grid、form-input -
@type要写标准类型名：color、number、string、list、map，别写成String或Color -
@param必须紧跟在 mixin/function 声明正上方，且顺序、名称、类型要和函数签名严格一致：
/// 创建响应式断点容器
/// @param {number} $min-width - 最小宽度阈值（单位 px）
/// @param {string} $class-suffix - 生成的 class 后缀名
@mixin responsive-container($min-width, $class-suffix) { ... }局部文件（_partial.scss）里的注释不会单独生成页面
这是最容易误解的一点：即使你在 _mixins.scss 里写了满屏 /// 注释，只要这个文件没被 @import 到入口文件（如 index.scss），sassdoc 就根本不会扫描它。工具只遍历你显式指定的入口路径及其直接依赖树。
- 确保你的入口 SCSS 文件（如
src/styles/index.scss）里有@import "mixins"，而不是只靠 IDE 自动索引 - 如果用了
@use语法（Dart Sass 推荐），需确认 sassdoc 版本 ≥ 2.7.0，旧版对@use支持不完整 - 运行命令时路径要对：
sassdoc src/styles/index.scss，而不是sassdoc src/styles/_mixins.scss
生成的文档里看不到变量实际值？检查 @return 和 @example
默认情况下，sassdoc 只展示变量声明和注释，不渲染计算结果。想让文档里显示 $spacing-xs: 4px 这样的具体值，得靠 @example；想让 function 文档里出现返回值示例，得用 @return 标签并配真实调用。
-
@example scss后必须换行，然后缩进写代码块（推荐 2 空格） - function 的
@return类型要准确，例如@return {string}，否则示例可能不渲染 - 别指望
@see能自动跳转 —— 它只生成纯文本链接，不支持锚点解析
/// 将像素值转为 rem（基于 16px 基准）
/// @param {number} $px
/// @return {string}
/// @example scss
/// font-size: px-to-rem(24);
@function px-to-rem($px) {
@return #{$px / 16}rem;
}真正卡住多数人的，从来不是语法写错，而是忘了 sassdoc 不读取编译后 CSS、不分析运行时逻辑、也不理解你项目里自定义的命名空间规则 —— 它只认三件事：/// 开头、紧贴声明、路径可达。其他全是干扰项。
