CODEWITHSUNDEEP
swiftxcodeswift3xcode8
Vince O'Sullivan
Vince O'Sullivan

Reputation: 2701

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

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?

enter image description here

Upvotes: 10

Views: 817

Answers (3)

Kevin Owens
Kevin Owens

Reputation: 548

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.

Upvotes: 1

Ankit Thakur
Ankit Thakur

Reputation: 4749

If you want the documentation to show for, then you need to show in comments as:

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

enter image description here

Upvotes: 0

pedrouan
pedrouan

Reputation: 12910

the "for" word is not mandatory word, it is optional for better understanding of the code, when used.

In the Swift 3 book stands:

The use of argument labels can allow a function to be called in an expressive, sentence-like manner, while still providing a function body that is readable and clear in intent.

Without this word, writing the code would be

let myWeather = conditions(myLocation)

When we define methods, it is always fine to use words like with:, using:, for:, withLabel: etc.

Upvotes: 0

Related Questions