如何在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）但该文本正确显示在快速帮助窗口中

我想我们需要等待（希望）Apple修复此问题。

尽管有一点改善。不用在每一行写“ Parameter”，而是使用以下语法：

- Parameters:
  - name1: description
  - name2: description

（缩进似乎很重要）

那么你会得到

但是在所有调用该函数的地方都行不通...