Argument labels before parameters in functions - possible bug in Swift Markup?

Question

I have the following function in a class:

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

which is called as follows let myWeather = conditions(for: myLocation).

The code works fine, the question is about the documentation. The image below is what is seen in the 'quick help' window for the conditions function. Given that the user of the function must use the external argument label (for) and also that I have explicitly documented that label, shouldn't the parameters line in the quick help window read Parameters for and not Parameters location?

Is this a bug in Xcode or is there a reason the (internal) parameter name is displayed and not the external argument label?

Answer 1

Quite simply, for is not the parameter; location is. And quick help is documenting parameters.

Preferring that quick help identify for as a location on the Earth's surface, as has been suggested, would be a bit puzzling to the reader.

The SPLG and API Design Guidelines use the terminology "parameter" and "argument label" (as in your question title) instead of "internal parameter" and "external parameter" (which may lead to the confusion you're raising). Given this, parameters fall under the Parameters heading in quick help, and argument labels appear in the Declaration.