Discussion about escaping vs non-escaping closures is too vague

[slavapestov]

Location

No response

Description

Documentation for escaping vs non-escaping is split between two places:

• The Closures chapter
• The Types chapter

The description is insufficiently precise, and it suggests that all function types are non-escaping except for parameters that are @escaping, but that's actually backwards.

Here is an example illustrating the implemented semantics:

func f(_ fn1: () -> (),             // non-escaping: parameter position
       _ fn2: @escaping () -> (),   // escaping: explicit attribute
       _ fn3: Array<() -> ()>)      // escaping: not parameter position
    -> () -> ()                     // escaping: not parameter position
  let fn4 = fn1                     // non-escaping: inferred type
  let fn5: () -> () = { }           // escaping: not parameter position
}

Also, there are not enough examples. The "Closures" section seems to only have one example of the @escaping attribute being used. In "Types", there is more discussion about the exclusivity checking restrictions and some more mention of escaping vs non-escaping function types, but no cross-reference to the "Closures" section, and also no examples shown, and in fact the only mention of the attribute spelling itself is in the middle of an aside:

In the code above, both of the parameters to takesTwoFunctions(first:second:) are functions. Neither parameter is marked @escaping, so they're both nonescaping as a result.

Correction

No response