GSoC 2026：为 C++ 扩展 Clang API Notes：函数与方法的特定重载注解
内容提要
GSoC 2026 项目为 Clang API Notes 扩展 C++ 重载专用注解：在 YAML 中新增 Where 块，可按参数类型和对象限定符（const、引用等）精确匹配单个函数或方法重载，并支持类型别名与空参数列表。实现涵盖解析、序列化、Sema 集成与诊断，同时保持原有仅按名称匹配行为的兼容性。
延伸解读
重载选择器的设计动机
C++ 中同名函数或方法可能因参数类型不同而构成重载，仅凭名称无法区分。API Notes 原先只能按名称匹配，导致无法为不同重载分别指定注解。新引入的 Where 块允许通过参数类型和对象限定符精确选择单个重载，同时保持原有仅按名称匹配的行为不变，确保现有 API Notes 文件继续有效。
类型匹配的规范化策略
匹配参数类型时，实现会先尝试声明中写出的类型（如别名 Count），若无匹配再回退到去糖后的底层类型（如 int）。同时会规范化不影响重载身份的拼写差异，如空格、指针引用符号、模板逗号等，并移除顶层 const/volatile 和选择器中的空值性。这种策略在保留源级区分的同时，避免因无关差异导致匹配失败。
对象限定符的匹配机制
成员函数的隐式对象参数可带有 const、volatile 和引用限定符，这些限定符能区分仅靠显式参数无法区分的重载，例如 operator[] 的 const 与非 const 版本。Where.Object 块允许指定这些限定符，如 Const: true 或 Ref: lvalue，从而精确选择目标重载。静态方法和非成员函数没有隐式对象参数，对其使用 Object 约束会被诊断为无效。
实现范围与兼容性保障
项目覆盖了从 YAML 解析、二进制序列化、声明查找、Sema 集成到诊断的完整流程，并拆分为多个独立补丁以便审查。实现中特别保留了旧有仅按名称查找的行为：先按名称和上下文查找，再根据显式参数类型筛选重载专用条目。序列化时还区分了省略参数约束与显式空参数列表，确保语义不丢失。
Q&A
GSoC 2026 的 Clang API Notes 项目主要想解决什么问题？
该项目旨在让 API Notes 能够针对 C++ 函数和方法的特定重载进行注解，而不是仅按名称匹配整个重载集。
如何在 API Notes 的 YAML 中指定一个特定的 C++ 重载？
在 Functions 或 Methods 条目下添加可选的 Where 块，通过 Where.Parameters 指定参数类型列表来缩小匹配范围。
API Notes 如何区分 const 和非 const 的成员函数重载？
使用 Where.Object 约束，通过 Object.Const 设置为 true 或 false 来分别匹配 const 和非 const 重载。
Where.Parameters 省略和显式空列表 [] 有什么区别？
省略 Where.Parameters 表示不约束参数列表，条目适用于所有同名重载；显式空列表 [] 则只匹配没有显式参数的声明。
API Notes 在匹配参数类型时如何处理类型别名？
查找时先尝试声明中写出的或 sugared 类型，如果没有匹配条目，则回退到适当 desugared 的表示，因此别名特定的选择器优先，底层类型选择器作为回退。
实现重载特定注解需要修改 Clang 的哪些部分？
需要修改 YAML 解析、API Notes 数据模型、二进制序列化、声明查找、Sema 集成以及诊断，并保持原有仅按名称匹配的行为兼容。
项目是否支持 C++ 模板的重载匹配？
目前不支持函数模板匹配，但项目探索了未来扩展的设计，例如使用深度和索引的结构化模板参数标识。
