Swift 4中如何为函数的可选闭包参数编写文档？

你遇到的这个问题很典型——因为闭包的内部参数不属于函数的顶层参数列表，直接把它和函数参数同级写注释的话，文档生成工具（比如Xcode的快速帮助）是识别不到的。下面给你两种实用的解决方式：

方式一：嵌套参数注释 #

利用文档注释的缩进嵌套特性，把闭包内部参数的说明放在对应闭包参数的注释下面，让文档工具能识别层级关系：

/// 示例函数
/// 执行指定操作，可选择通过闭包接收状态回调
///
/// - Parameter optionalClosure: 一个可选的状态回调闭包
///   - aClosureParameter: 闭包传入的布尔值参数，用于标记操作是否执行成功
func exampleMethod(optionalClosure: ((_ aClosureParameter: Bool) -> Void)?) {
    // 执行操作
}

这种写法会让Xcode的快速帮助里，aClosureParameter作为optionalClosure的子项显示出来，层级清晰，一目了然。

方式二：在闭包参数描述中直接说明 #

如果不想用嵌套列表，也可以在闭包参数的描述文本里直接强调闭包参数名，用反引号突出参数标识：

/// 示例函数
/// 文档内容
///
/// - Parameter optionalClosure: 可选闭包，调用时会传入一个布尔类型的参数`aClosureParameter`，该参数用于传递操作的执行状态
func exampleMethod(optionalClosure: ((_ aClosureParameter: Bool) -> Void)?) {
    // 执行操作
}

关键逻辑 #

核心原因是：aClosureParameter是闭包类型的一部分，不属于exampleMethod的直接参数，所以不能和optionalClosure平级写注释，必须把它的说明归到对应闭包参数的文档范围内，这样文档工具才能正确解析展示。

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