Swift中如何抑制“External name used to document parameter”警告？

这个警告的核心原因是：Swift的文档注释中，- parameter标签要求关联参数的内部名称，而你用了参数的外部名称来写注释，因此触发了该警告。你习惯用in...作为参数内部名，同时保留外部名供调用者使用，但注释里想匹配使用者视角写外部名，这就和编译器的要求产生了冲突。

以下是两种可行的解决思路：

思路1：遵循Swift注释规范（推荐） #

直接在- parameter后使用参数的内部名称即可，Swift的文档生成工具（包括Xcode代码提示、第三方文档生成器如Jazzy）会自动关联并展示参数的外部名称给使用者，完全不影响调用者查看文档体验。

修正后的代码示例：

/* ################################################# */
/**
 Perform a server-based search.
 
 - parameter inMinNumber: The minimum number of results to return.
 - parameter inSpecification: The search specification.
 - parameter inCompletion: A tail completion proc (may be called in any thread).
 */
public func meetingAutoRadiusSearch(minimumNumberOfResults inMinNumber: Int, specification inSpecification: SearchSpecification, completion inCompletion: @escaping QueryResultCompletion) {
    // 函数实现
}

调用者在使用时查看代码提示，依然能看到外部名minimumNumberOfResults、specification等，以及你编写的注释内容。

思路2：强制抑制警告 #

如果你坚持要在注释中使用外部名称，可以通过Clang编译指令临时屏蔽该警告，避免Xcode报错：

/* ################################################# */
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wdocumentation-external-param-name"
/**
 Perform a server-based search.
 
 - parameter minimumNumberOfResults: The minimum number of results to return.
 - parameter specification: The search specification.
 - parameter completion: A tail completion proc (may be called in any thread).
 */
#pragma clang diagnostic pop
public func meetingAutoRadiusSearch(minimumNumberOfResults inMinNumber: Int, specification inSpecification: SearchSpecification, completion inCompletion: @escaping QueryResultCompletion) {
    // 函数实现
}

#pragma clang diagnostic push/pop仅对中间的代码段生效，不会影响其他部分的警告检查。

补充说明：Xcode的这个限制是为了确保注释和参数定义的强关联——参数的内部名是代码中唯一的标识，外部名可能被修改，用内部名写注释能避免后续参数名变更时注释和代码脱节的问题。

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