用途:设计、审查或改进 Swift API,使声明在使用点清晰、调用流畅,并符合既有的 Swift 命名与标签约定,优先保证可读性、明确意图以及声明、调用点和文档注释之间的一致性。
主要能力:检查声明与调用点;检查命名清晰度与流畅性;检查参数标签与参数命名;检查文档注释与符号标记;检查约定与重载安全性。改进时重命名含糊、冗余或角色不清的 API;重构标签改善调用点的语法阅读;用基于角色的名称替换弱命名参数;解决弱类型导致的模糊重载;强化文档摘要以准确描述行为与返回值。新建功能时先从使用点示例出发,再确定声明;选择基础名与标签使调用读起来像清晰的英语短语;仅在简化常见用法时添加默认值;以一致命名定义 mutating/nonmutating 对;为每个新声明添加简洁文档注释。
核心规则:使用点清晰优先于简洁;每个声明都应有文档注释,摘要说明其做什么、返回什么、访问什么、创建什么或是什么,并使用 Parameter、Returns、Throws、Note 等 Swift 符号标记。包含避免歧义所需的全部词,省略多余词(尤其是类型重复),按角色而非类型命名参数与关联类型;类型信息弱时(Any、NSObject、String、Int)添加角色名词。方法名应产生语法正确、可读的调用点;工厂方法以 make 开头;无副作用 API 用名词短语,有副作用 API 用祈使动词;保持 mutating/nonmutating 命名成对一致(sort/sorted、formUnion/union);布尔 API 读作断言(isEmpty、intersects)。术语方面优先常用词,除非领域术语确有必要并保留其既定含义,避免非标准缩写。约定方面:非 O(1) 计算属性需记录复杂度;除特殊情况外优先使用方法/属性而非自由函数;遵循 Swift 大小写约定,包括首字母缩写处理;默认参数置于末尾,共享语义时优先用默认参数而非方法族;参数标签依据语法与含义而非风格偏好。
使用方式:按决策树执行——审查现有代码、改进现有代码、实现新功能;参考资料包括 references/fundamentals.md、references/promote-clear-usage.md、references/strive-for-fluent-usage.md、references/use-terminology-well.md、references/general-conventions.md、references/parameters.md、references/argument-labels.md、references/special-instructions.md。
适用场景:Swift API 的设计、评审、重构与文档完善,尤其是公共 API 表面。
限制:官方文本暂未提供;具体安装或调用命令暂未提供;以上内容依据给定资料整理,未提供的功能、收费、价格、平台或效果不作推断。