函数中参数之前的参数标签 - Swift Markup中可能出现的错误？

Question

我在课堂上有以下功能：

/// Returns the weather conditions at the given location.
/// - parameter for: A location on the Earth's surface.
/// - returns: If found, the `WeatherConditions` at the supplied location otherwise nil.
public func conditions(for location: Location) -> WeatherConditions? {
    return nil  // The actual code is not important to the question.
}

，其名称如下let myWeather = conditions(for: myLocation)。

代码工作正常，问题是关于文档。下面的图片是“快速帮助”中的内容。 conditions函数的窗口。鉴于该函数的用户必须使用外部参数标签（for）并且我已明确记录该标签，不应该在快速帮助窗口中的参数行读取Parameters for和不是Parameters location？

这是Xcode中的错误还是显示（内部）参数名称而不是外部参数标签的原因？

Answer 1

很简单，for不是参数; location是。快速帮助记录参数。

如果有人建议的话，首选快速帮助将for标识为地球表面上的某个位置，对读者来说会有点令人费解。

SPLG和API Design Guidelines使用术语＆＃34;参数＆＃34;和＃34;参数标签＆＃34; （如在你的问题标题中）而不是＆＃34;内部参数＆＃34;和＆＃34;外部参数＆＃34; （这可能会导致你提出的混乱）。鉴于此，参数属于快速帮助中的参数标题，参数标签出现在声明中。

Answer 2

“for”字不是强制性字，在使用时可以选择更好地理解代码。

在Swift 3书中：

  

使用参数标签可以以富有表现力的类似句子的方式来调用函数，同时仍然提供可读的函数体意图明确。

没有这个词，编写代码将是

let myWeather = conditions(myLocation)

当我们定义方法时，总是可以使用如下的单词：，使用：，for：，withLabel：etc。

Answer 3

如果您希望显示文档，则需要在评论中显示为：

/// Returns the weather conditions at the given location.
/// - parameter `for Location`: A location on the Earth's surface.
/// - returns: If found, the `WeatherConditions` at the supplied location otherwise nil.
public func conditions(for location: CLLocation) -> AnyObject? {
    return nil  // The actual code is not important to the question.
}