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

Question

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:

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

Answer 1

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).

Answer 2

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

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

3 ) BUT the text appears correctly in the quick help window

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

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