如何修复或抑制Xcode12.4中的孤立文档注释类警告

触发的典型警告内容为：Orphaned Doc Comment Violation: A doc comment should be attached to a declaration. (orphaned_doc_comment)，本质是SwiftLint联动Xcode校验时，发现三斜杠格式的文档注释///没有绑定到需要解释的代码声明，通常由注释和被解释代码之间留空行、隔了无关代码导致。

合规修复方案（优先推荐） #

• 调整注释位置，让///文档注释紧贴对应的代码声明（类、方法、属性、枚举等），中间不留空行或插入无关内容。
  触发警告的错误写法：

  /// 支付方法功能说明
  
  func handlePayment() {}
  

  无警告的正确写法：

  /// 支付方法功能说明
  func handlePayment() {}
  

• 若注释和被解释代码之间无法避免间隔，将三斜杠文档注释替换为普通双斜杠注释//，普通代码注释不会触发文档注释的归属校验。
• 若为代码迭代残留的、无对应解释目标的///注释，直接删除该部分无用内容即可。

特殊场景警告抑制（不建议作为常规写法） #

受业务逻辑、代码架构限制无法调整注释位置时，可通过规则屏蔽消除警告：

• 局部代码块屏蔽：在触发警告的注释行前后添加SwiftLint规则开关标记，仅跳过该段注释的规则校验：

  // swiftlint:disable orphaned_doc_comment
  /// 此处暂时无绑定声明的注释
  // swiftlint:enable orphaned_doc_comment
  

• 全局屏蔽：在项目根目录的.swiftlint.yml配置文件中，将orphaned_doc_comment加入disabled_rules数组，全项目范围关闭该条校验规则。

内容的提问来源于stack exchange，提问作者Saranjith