在Swift 3 中如何记录函数的闭包参数？

Question

在Xcode 8 beta和Swift 3中，当你有一个方法将闭包作为参数时，例如：

func foo(bar: (String) -> Void) {
    bar("Hello, world")
}

您如何记录闭包采用的参数？例如，如果我这样写：

/// Calls bar with "Hello, world"
/// - parameter bar: A closure to call
func foo(bar: (String) -> Void) {
    bar("Hello, world")
}

那么快速帮助是这样的：

我想知道允许我写一些文本来替换的语法是什么"No description."非常感谢！

Answer 1

据我所知，如果你标记它们，你只能记录闭包参数：

/// Calls bar with "Hello, world"
/// - parameter bar: A closure to call
/// - parameter theString: A string to use
func foo(bar: (theString: String) -> Void) {
    bar(theString: "Hello, world")
}

这不太理想：它强制您在调用闭包时使用参数标签，如果存在命名冲突，似乎无法区分两者。

编辑：正如@Arnaud 指出的那样，您可以使用_ 来避免在调用闭包时必须使用参数标签：

/// Calls bar with "Hello, world"
/// - parameter bar: A closure to call
/// - parameter theString: A string to use
func foo(bar: (_ theString: String) -> Void) {
    bar("Hello, world")
}

事实上，这是 Swift 3 中唯一有效的方法，因为参数标签不再是类型系统的一部分（参见 SE-0111）。

Answer 2

这个好像坏了好久了。这是 XCode 11.6 的示例，您可以在其中看到：

1 ) 参数记录在@Tim Vermeulen 回答中

2 ) 然而，“无描述” table 出现在帮助 pop-over window

3 ) 但是文本在快速帮助中正确显示 window

我想我们需要等待（希望）Apple 解决这个问题。

虽然略有改善。不要在每一行都写“参数”，而是使用以下语法：

- Parameters:
  - name1: description
  - name2: description

（缩进似乎很重要）

然后你会得到

但并不是所有调用该函数的地方都有效...

在Swift 3 中如何记录函数的闭包参数？

How do you document the parameters of a function's closure parameter in Swift 3?

swift

xcode

markup