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

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

然后，快速帮助如下所示：

我想知道什么语法可以使我写一些文字来代替“无描述”。非常感谢！

swift xcode markup

— 索伦·莫滕森
source

Answers:

据我所知，只有标记了闭包参数，您才能记录它们：

/// 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）。

— 蒂姆·维穆伦
source

这绝对可以回答我的问题，谢谢！我实际上不知道您可以在闭包中添加参数标签！那真是个好消息。相反，我认为这一点也不理想。参数标签使代码更易于理解，恕我直言，我宁愿拥有参数标签而不是使用完全匿名的参数调用闭包。

— 索伦·莫特森

是的，我同意。这将是非常好的，如果你能这样做- parameter $0: Description，或许经过进一步缩进- parameter bar

— 索伦·莫特森

请注意，您可以编写(_ theString: String)文件以具有本地参数名称（出于文档目的），而不必在调用站点上使用它。实际上，由于Xcode 8 beta 6，您必须这样做，否则编译器会抱怨“函数类型不能具有参数标签”。有关详细信息，请参见SE-0111和此电子邮件。

— Arnaud

尽管这允许标签出现，但我仍然看到其详细信息中的“无描述”。有人真的找到了解决方法吗？我实际上想显示一个适当的描述。

— wuf810 '17

我遇到与@ wuf810相同的问题。即使我标记了closure参数并添加了它的描述，它仍然显示一个正方形，说它没有该参数的描述。

— 大卫·塞斯佩德斯

这似乎已经被打破了一段时间。这是XCode 11.6的示例，在其中您可以看到：

1）参数记录如@Tim Vermeulen答案中所述

2）但是，“无描述”表仍显示在帮助弹出窗口中

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

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

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

- Parameters:
  - name1: description
  - name2: description

（缩进似乎很重要）

然后你会得到

但这并不是在所有调用函数的地方都起作用...

— 艾格赛恩
source