To satisfactorily name and control usage of APIs that include potentially trailing closures, what tools does an author need?
Glossary
-
FTC = as actually used at a call site, a first trailing closure.
-
PTC = as viewed at the declaration site, a potentially trailing closure; i.e., a function/method parameter requesting a closure which parameter is positioned within the list of parameters such that it could be satisfied at the call site with a trailing closure.
-
PFTC = as viewed at the declaration site, a potential first trailing closure; i.e., a function/method parameter requesting a closure which parameter is positioned within the list of parameters such that it could be satisfied at the call site with a trailing closure that could be a FTC.
-
Parameters = in the declaration of a function/method, the typed values that are to be the inputs.
-
Arguments = at the call site, the values actually provided to a function/method.
-
Parameter Name = at the declaration site of a function/method, the name given to a parameter; i.e., the name used within the function body.
-
Argument Labels = as defined at the declaration site of a function/method and as used at the call site, the label for an argument; at the declaration site, if an argument label is specified, it precedes the parameter name, and if it is intended that no label is to be used for a given argument, a
_is specified as the argument label, and if it is intended that the parameter name also should serve as the argument label, then no argument label is specified.
Proposed Tool Kit:
-
The ability for the caller to actually apply a label to a FTC. See @xwu's brilliant proposal.
-
The ability to require that a caller apply a label to a FTC. To be source compatible, some sort of annotation of the function/method declaration would be required. I believe this annotation would operate on the entire declaration rather than on a parameter-by-parameter basis.
-
The ability to rewrite existing APIs that may not have labels so that they properly can take advantage of (1) and (2). We already have the
@available(*, deprecated, renamed: "theNewName")annotation, which could be used to mark old function/method declarations so that they will be (mostly) ignored by autocomplete and so that a new function, with the same name but added labels, can be added. If an API author chooses to so deprecate a function/method, it will continue to be present for backward compatibility, but the tooling will issue a warning to the user along with a fixit to use the new function/method. -
A minor revision of the language documentation to specify that a user may omit the argument label from a FTC if permitted by the API being called. The current documentation, of course, says that a user must omit the argument label from a FTC.
-
Maybe the ability to specify to the autocomplete tooling whether or not to prefer trailing closures for a particular function/method, and if so, perhaps the ability to specify which closure parameter should be preferred as being the best candidate for usage as a FTC.
Would that suffice? Does this tool kit fit well with the principles established by the Core Team?
[EDIT: In the first 30 minutes of this post's life, I made a variety of formatting edits, and added items 4 and 5 to the tool kit. Apologies for any confusion.]