How to Document the Parameters of a Function'S Closure Parameter in Swift 3

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

How to document optional closure function parameters?

I cannot tell if that is intentional or a bug, but a workaround is
to declare the parameter type using Optional instead of ?:

/// An example function.
/// Documentation goes here.
///
/// - Parameters:
///   - optionalClosure:    An optional closure.
///   - aClosureParameter:  This **will** be displayed.
func exampleMethod(optionalClosure: Optional<(_ aClosureParameter: Bool) -> Void>) {
    // Do something
}

How to pass closure with parameters to a function? (Swift)

I think you're misunderstanding how default parameters work. Default parameters are just a syntax helper. They make it easier to call the function directly in code, but they don't change the function itself. There's no way that you could support any number of parameters if they were actually required; you'd need to pass something.

So just expand this to make the syntax convenience explicit with an overload:

func myFunction(_ str1: String?, _str2: String?)
{
    //whatever
}

func myFunction() {
    myFunction(nil, nil)
}

And then you can call it.

func delay(_ function: @escaping () -> Void)
{
    if !myExternalCondition
    {
        DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
            self.delay(function)
        }
    }
    else
    {
        function()
    }
}

It's possible you've just misunderstood how closures work. With the above delay, the following is fine using your original definition of myFunction (with default parameters):

delay { myFunction() }

The following is also fine:

delay { myFunction("xyz") }

The point is that the closure has no parameters. You may be thinking of myFunction as the "closure" but that's not correct. The closure is the {...} part. If it had parameters, you'd expect a x in syntax or $0 somewhere in it.

Swift: does capturing a function parameter, within a closure, hold it strongly?

Closure capture parameters strongly by default. In most common cases in closure you accessing to properties declared in self, without capturing other references, so making self weak is enough. In your case you need expand closure capture list and include tableView to it:

func someFunction(tableView: UITableView) -> (() -> ()) {
    return { [weak self, weak tableView] in
        self?.someOtherFunction() {
            tableView?.performTask()
        }
    }
}

You may read more about capture lists in ARC documentation:

You resolve a strong reference cycle between a closure and a class
instance by defining a capture list as part of the closure’s
definition. A capture list defines the rules to use when capturing
one or more reference types within the closure’s body. As with strong reference cycles between two class instances, you declare each
captured reference to be a weak or unowned reference rather than a
strong reference.

Swift numbered function arguments

Those are called "Anonymous Closure Arguments" or "Shorthand Argument Names". They only work for closures, not functions.

Method parameters in nested closure

You are correct, captured variables will last for the life of the closure. Here's an exert on capturing variables from apple's swift documentation:

A closure can capture constants and variables from the surrounding
context in which it is defined. The closure can then refer to and
modify the values of those constants and variables from within its
body, even if the original scope that defined the constants and
variables no longer exists.

In Swift, the simplest form of a closure that can capture values is a
nested function, written within the body of another function. A nested
function can capture any of its outer function’s arguments and can
also capture any constants and variables defined within the outer
function.

https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/Closures.html

---

Related Topics