如何在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")
}

然后快速帮助看起来像这样:

我想知道什么语法可以让我写一些文字来取代"没有描述".非常感谢!

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 ) 尽管如此，“无描述”表出现在帮助弹出窗口中

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

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

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

- Parameters:
  - name1: description
  - name2: description

（缩进似乎很重要）

然后你会得到

但它在调用函数的任何地方都不起作用......