SourceFile.md

Winyunq 风格：源文件注释规范 (Source File Comment Style)

本文件描述了 Winyunq 风格中 /// 注释的默认使用规范，主要应用于源文件中的声明和定义体内部。

4. /// - 默认的本地上下文提供者 (强制基础规则)

• 4.1 核心作用: 为所有声明，以及定义体内部的语句、成员等提供即时、简洁的上下文。这是 Winyunq 风格的默认注释方式。凡是未加以说明的地方，均默认使用///
• 4.2 强制应用场景:
  • 预处理指令 (#include, #pragma once 等)。
  • 所有声明: 函数原型 (/// @brief)，类/结构体前向声明 (/// @brief)，外部变量声明 (extern)，using 声明/指令, typedef 等。
  • 类/结构体/枚举 定义体 {} 内部: 访问控制符 (public:), 成员变量声明, 成员函数声明 (/// @brief)，枚举值。
  • 函数 定义体 {} 内部: 局部变量声明, 控制流语句 (if, for, while, switch 等的条件和主体语句), 可执行语句 (函数调用, 赋值等), return 语句。
• 4.3 格式规则 (强制):
  • 位置: 必须在被描述代码行的正上方。
  • 间距: 与代码行之间禁止任何空行。
  • 缩进: 必须与代码行完全相同的缩进。
    • 目的 (Purpose for 上方/无空行/同缩进): 创建代码与其解释之间最紧密的视觉和逻辑绑定。
  • 内容:
    • 必须简洁，且必须为单行。 任何需要多行解释或详细说明的情况，都应将信息整合到包含该元素的定义的 /** 文档中。
    • 函数声明(原型) 必须使用 /// @brief [描述]，且此 @brief 必须是单行。
    • 绝对禁止在 /// 注释中使用 @details, @param, @return, @note, @warning, @tparam, @extends 等任何块级 Doxygen 标签。
      • 目的 (Purpose for 单行强制 & 禁止块标签): 强制 /// 只承担最核心、最本地的上下文描述。确保极致简洁，将结构化、详细文档责任完全推向 /** 定义块。维护 /// 与 /** 的严格功能分离。
    • 禁止在仅包含 { 或 } 的行上方使用 ///。