How do you document the parameters of a function's closure parameter in Swift 3?

SwiftXcodeMarkup

Swift Problem Overview


In Xcode 8 beta and Swift 3, when you have a method that takes a closure as a parameter, for example:

func foo(bar: (String) -> Void) {
    bar("Hello, world")
}

How do you document the parameters the closure takes? For example, if I wrote this:

/// Calls bar with "Hello, world"
/// - parameter bar: A closure to call
func foo(bar: (String) -> Void) {
    bar("Hello, world")
}

Then the quick help looks like this:

foo(bar:) Quick Help

I would like to know what the syntax is that will allow me to write some text to replace "No description." Many thanks!

Swift Solutions


Solution 1 - Swift

As far as I know, you can only document the closure parameters if you label them:

/// Calls bar with "Hello, world"
/// - parameter bar: A closure to call
/// - parameter theString: A string to use
func foo(bar: (theString: String) -> Void) {
    bar(theString: "Hello, world")
}

This is less than ideal: it forces you to use an argument label when you call the closure, and if there are naming conflicts, there seems no way to distinguish between the two.

Edit: As @Arnaud pointed out, you can use _ to prevent having to use the parameter label when calling the closure:

/// Calls bar with "Hello, world"
/// - parameter bar: A closure to call
/// - parameter theString: A string to use
func foo(bar: (_ theString: String) -> Void) {
    bar("Hello, world")
}

In fact, this is the only valid approach in Swift 3 because parameter labels are no longer part of the type system (see SE-0111).

Solution 2 - Swift

This seems to be broken for quite some time. Here is an example with XCode 11.6, where you can see that :

1 ) the parameters are documented as explained in @Tim Vermeulen answer enter image description here

2 ) nevertheless, the "no description" table appears in the help pop-over window enter image description here

3 ) BUT the text appears correctly in the quick help window enter image description here

I guess we need to wait (hope) for Apple to fix this.

A slight improvement, though. Instead of writing "Parameter" at each line, use the following syntax :

- Parameters:
  - name1: description
  - name2: description

(indentation seems to be important)

Then you'll get enter image description here

But it doesn't work everywhere the function is called...

Attributions

All content for this solution is sourced from the original question on Stackoverflow.

The content on this page is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

Content TypeOriginal AuthorOriginal Content on Stackoverflow
QuestionSøren MortensenView Question on Stackoverflow
Solution 1 - SwiftTim VermeulenView Answer on Stackoverflow
Solution 2 - SwiftAirXygèneView Answer on Stackoverflow