You are confusing the declaration (what is shown in the docs) with the call (what is in your code). For each parameter, the declaration shows the argument label (if different than the parameter name) followed by a spce, the parameter name followed by a colon, and the type ot the parameter. When you call the function, if an argument label is in the declaration, you type the argument label (unless _ is specified in the declaration) followed by a colon, then the actual parameter you want to pass. If no argument label is given, you type the parameter name followed by a colon, then the actual parameter you want to pass. In your example #selector is how you create a variable of type Selector, and .touchUpInside a case of the UIControlEvents enumeration type. If an argument label is given in the declaration, the parameter name is not used when you call the function; it is used by the code inside the function when it wants to access the parameter. If you write your own functions and you specify both an argument label and a parameter name, your code inside the function would need to use the parameter name. See "Function Argument Labels and Parameter Names" here for the full explanation in the Swift 3 manual.
You are correct, though, that some of the documentation (especially the newer Swift versions of things) has very little information.
EDIT: Added "If an argument label is given in the declaration, " to the start of the 5th sentence.
EDIT 2: Clarified a few things.
BTW to file an official enhancement request, use the bug reporter (Report Bugs link at bottom right of forum pages). When you create a bug report, you can choose Enhancement Request as one of the options. You can file bug reports and enhancement requests against the documentation.