How do you document the parameters of a function's closure parameter in Swift 3?
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).
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...