本技能描述 bocpy 项目中统一的注释与文档约定，供在新增或修改注释时遵循，以保持代码库一致。
用途：为 C 与 Python 文件添加注释、编写 docstring、记录结构体或类。
C 文件（如 _core.c、_math.c）：
- 函数级文档使用 Doxygen 的 /// 风格，置于函数签名正上方，标签顺序为 @brief、@details、@note、@param、@return。@brief 为单行摘要，句首大写、句末不加句号；@param 每个参数一条，描述首字母大写。简单辅助函数仅需 @brief 和 @return。
- 结构体字段用字段上方 /// @brief（可加 /// @details）说明。
- 行内注释用 //，默认单行且不超过 120 字符，置于所描述代码上一行并与当前缩进对齐；仅当记录代码无法表达且一行放不下的内容（如并发不变式、X-macro 表边界等）才允许多行。行尾 // 仅用于预处理版本标注。
- /* / 块注释仅作哨兵标记，例如 {NULL} / Sentinel */；例外是 X-macro 描述表上方的多行块注释，需列出用途、新增 op 方式、符号命名方案和表达式作用域内名称。
- PyMethodDef 表用简短单短语描述；PyModuleDef 的 .m_doc 写简短模块说明。
- TODO 用独立一行的 // TODO，后接条目。
Python 文件：
- 每个 .py 文件以单行三引号 docstring 开头，句首大写、以句号结尾。
- 类 docstring 置于 class 语句后，简单类用单行，复杂类用摘要行、空行、详细描述。
- 函数/方法 docstring 以祈使语气动词开头，简单函数单行，复杂函数多行，均以句号结尾。
- 参数文档统一使用 Sphinx 的 :param:、:type:、:return:、:rtype: 字段。
- .pyi 存根文件的公开函数、类、常量使用 Sphinx 风格 docstring；常量在声明下一行使用属性 docstring。
- 行内 # 注释规则与 C 的行内 // 一致：默认单行不超过 120 字符，置于上一行并对齐缩进；仅记录无法表达且一行放不下的内容才允许多行；同行 # 注释可用于极短标注。
- 用 # noqa: CODE 抑制 linter 警告，须放在实际违规所在行，而非包裹的 def 或装饰器行。
- 代码生成插入点使用 # BEGIN boc_export 与 # END boc_export 标记。
lint 规则（flake8，配置在 .flake8）：inline-quotes 为 double（Q000）；max-line-length 为 120；docstring-convention 为 google 并搭配 Sphinx :param: 字段；extend-ignore 为 E203、N812、N817；test/* 每文件忽略 D103、D403。
多行类 docstring（D205/D209）：须有摘要行、空行、正文，结束三引号独占一行。测试函数名必须小写，如 test_t_equals_transpose。
常见问题：C 文档勿用 /* */；勿用 Google 风格 Args: 而应用 Sphinx :param:；C 注释勿漏 @brief；Python docstring 勿漏句末句号；C 的 @brief 勿加句末句号；勿重复 // 与 /// 说明同一内容；# noqa: 勿放错行；多行类 docstring 摘要后须加空行；Python 强制双引号；Cown(m) 返回值不使用时不要赋值以免触发 F841。
限制：本资料仅提供该项目的注释与文档约定，未提供安装命令、平台支持、价格或其他使用步骤。