Menu
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?
512
To omit argument labels, use a _ before the parameter name. A parameter name is still necessary to access the argument's value inside the function. Omitting the argument label might be wanted to make the function more readable.
The argument label is used when calling the function; each argument is written in the function call with its argument label before it. The parameter name is used in the implementation of the function. By default, parameters use their parameter name as their argument label.
If a function takes another function as an argument in Swift, you do not need to specify a separate function and pass that as an argument. Instead, you can use a closure function. A closure is an anonymous function. It is a block of code that acts as a function but does not have a name.
In Swift, variadic parameters are the special type of parameters available in the function. It is used to accept zero or more values of the same type in the function. It is also used when the input value of the parameter is varied at the time when the function is called.
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.
157
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
