Swift-Format 文档注释验证规则对 rethrows 函数的处理探讨

背景介绍

在 Swift 编程语言中，rethrows 是一个特殊的关键字，用于标记那些本身不会抛出错误，但会"重新抛出"其闭包参数可能抛出的错误的函数。这种机制在 Swift 标准库中广泛使用，特别是在高阶函数如 map 和 filter 中。

问题描述

Swift-Format 工具的 ValidateDocumentationComments 规则目前会对带有 rethrows 关键字的函数产生一个警告，建议开发者移除文档注释中的 Throws: 部分，理由是这些函数"不会抛出任何错误"。然而，这种处理方式在实际开发中可能会引起困惑。

技术分析

从技术实现角度来看，rethrows 函数确实不会主动抛出错误，但它们会将闭包参数可能抛出的错误传递给调用者。因此，从 API 使用者的角度来看，这些函数确实可能抛出错误，文档中注明这一点对使用者非常重要。

在 Swift 生态中，文档生成工具如 DocC 明确允许为 rethrows 函数编写 Throws 文档注释部分。这表明社区普遍认为记录这些潜在的错误传递行为是有价值的。

解决方案建议

基于上述分析，建议对 ValidateDocumentationComments 规则进行以下调整：

1. 对于 rethrows 函数，不应强制要求移除 Throws 文档注释
2. 也不应强制要求必须包含 Throws 注释
3. 将决定权留给 API 设计者，让他们根据具体情况决定是否需要文档化错误传递行为

这种处理方式既保持了灵活性，又符合 Swift 社区的实际使用习惯。

实际影响

当前的行为可能会导致以下问题：

• 开发者被迫移除有用的错误信息文档
• API 使用者可能无法从文档中了解潜在的错误情况
• 与 Swift 生态中其他工具的行为不一致

最佳实践

对于使用 Swift-Format 的开发者，在当前版本中可以考虑：

1. 暂时忽略这类警告
2. 或者添加 // swift-format-ignore 注释来跳过特定检查
3. 关注该问题的后续进展，等待官方修复

对于 API 设计者，建议继续为 rethrows 函数编写 Throws 文档注释，以提供完整的 API 文档。

总结

文档工具应该服务于开发者的需求，而不是强制不合理的约束。对于 rethrows 函数的文档注释验证，Swift-Format 应该采取更灵活的策略，尊重开发者的文档编写意图，同时保持与 Swift 生态其他工具的一致性。