函数中参数之前的参数标签 - 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 使用术语“参数”和“参数标签”（如您的问题标题）而不是“内部参数”和“外部参数”（这可能会导致您感到困惑）提高）。鉴于此，参数位于快速帮助中的参数标题下，参数标签出现在声明中。

Answer 2

“for”字不是必填字，使用时为了更好地理解代码是可选的。

在 Swift 3 书架上：

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

没有这个词，写代码会是

let myWeather = conditions(myLocation)

当我们定义方法时，总是可以使用 with:、using:、for:、withLabel: 等词。

Answer 3

如果您希望文档显示，那么您需要在 cmets 中显示为：

/// 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.
}