10

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

4
  • 2
    I always found that a little strange, but my guess is that the "external parameter name" acts as a label for the call site and the "internal parameter name" as the actual name. The label is supposed to make the function call read a bit like a sentence or phrase. In Swift 3 conventions, these labels are regularly prepositions instead of nouns, and it'd make sense to describe parameters by their name (typically a noun) instead of a label (which can be a preposition). If my guess is right, I'd prefer —for clarity— they'd use "label" and "name" instead of "external" and "internal" name. Commented Aug 19, 2016 at 10:27
  • XCode should really be able to produce two version of the documentation. One for the consumers of the API without access to the source code, showing the external name only in the declaration line and using the external name for the parameter description. And another one for the implementor of the method, showing both names in the declaration and using the internal name in the parameter description. I don't think XCode can distinguish these two views yet.
    – Codo
    Commented Aug 19, 2016 at 11:18
  • @Codo I'm inclined to agree but doubt it would ever happen. Meanwhile, I've raised this as a bug (27921906). I'll update here with any response. Commented Aug 19, 2016 at 11:25
  • I also mainly see it as a bug. If XCode doesn't provide both an internal and external view, it should show the external view, thus only use the parameter name for in your code.
    – Codo
    Commented Aug 19, 2016 at 11:30

3 Answers 3

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.

0

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.

4
  • 1
    I guess Vince O'Sullivan wants to fix the documentation and not change the signature of his method. This doesn't really answer it.
    – Codo
    Commented Aug 19, 2016 at 11:12
  • But I don't understand why would we replace the word "location" in the documentation for the word "for". If it is parameter, it should represent the word, that we use in the code as a variable, doesn't it?
    – pedrouan
    Commented Aug 19, 2016 at 11:44
  • He asked "shouldn't the parameters line in the quick help window read Parameters for and not Parameters location", so that's why I put the answer with argument label stuff.
    – pedrouan
    Commented Aug 19, 2016 at 11:50
  • 1
    Even if the label can be and is omitted in the call, the parameter still requires a name in the documentation. For the callers of the method, the first name applies, i.e. for in this case. That's what one would expect in the documentation. The second name (location in this case), is the internal name used by the implementation of the method. It should be hidden for consumers.
    – Codo
    Commented Aug 19, 2016 at 11:55
0

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

2
  • 2
    Under parameters is says "No description", the internal name location is visible twice and the parameter description now appears as a bullet point of the general descriptions. That's even worse than the original output and certainly not what Vince O'Sullivan was looking for.
    – Codo
    Commented Aug 19, 2016 at 11:12
  • Because the description bullet uses the label+parameter compound, and the parameter section describes location only... I don't know... for me the documentation is clear.
    – pedrouan
    Commented Aug 19, 2016 at 11:47

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.