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

背景介绍

SwiftFormat 是 Swift 语言的代码格式化工具，其中包含一个验证文档注释的规则 ValidateDocumentationComments。这个规则会检查函数文档注释中的 Throws 部分是否与实际函数签名匹配。

问题现象

在 Mutex.swift 文件中，有一个使用 rethrows 关键字修饰的函数 withLock，其文档注释中包含 Throws 部分说明会重新抛出 body 闭包可能抛出的错误。然而 ValidateDocumentationComments 规则却给出了警告，建议移除 Throws 部分，理由是函数本身不会抛出任何错误。

技术分析

1. rethrows 关键字的作用：

   • rethrows 表示函数本身不会抛出错误，但如果传入的闭包参数抛出错误，函数会将这个错误重新抛出
   • 这是一种特殊的错误传播机制，介于 throws 和非 throws 之间

2. 文档注释验证规则的现状：

   • 当前规则将 rethrows 函数视为不抛出错误的函数
   • 这与实际使用场景存在差异，因为 rethrows 函数确实可能传播错误

3. 文档注释的最佳实践：

   • 对于 rethrows 函数，文档中说明错误传播行为是有价值的
   • 这有助于开发者理解函数的行为边界

解决方案建议

1. 规则调整方向：

   • 应该将 rethrows 视为一种特殊的 throws 情况
   • 对于 rethrows 函数，既不强制要求也不禁止 Throws 文档部分
   • 让开发者根据实际情况决定是否需要文档说明

2. 实际应用考量：

   • 对于简单的 rethrows 函数，可能不需要额外文档
   • 对于复杂的错误传播逻辑，文档说明可以提高代码可读性

总结

SwiftFormat 的文档注释验证规则在处理 rethrows 函数时存在一定的局限性。考虑到 rethrows 的实际语义和开发者的使用习惯，建议调整规则使其对 rethrows 函数采取更宽松的策略，允许但不强制要求 Throws 文档部分。这样既保持了代码规范的一致性，又不会限制开发者提供有价值的文档说明。