Add warnings for unused function arguments by default

[SDGGiesbrecht (Jeremy David Giesbrecht)]

@Braden_Scothern

if you customize the documentation rather than inheriting it from the protocols definition. Then you cans document the _.

You can do this instead:

/// Some description.
///
/// - Parameters:
///   - importantArg: Some description.
func someRequirement(importantArg: Int) {
  _ = importantArg
}

I did however notice while tinkering that the importantArg _: Int variant breaks the parameter section of any inherited documentation (at least in Xcode). That should probably be fixed.

[masters3d]

+1 yes please. Underscored internal argument name to silence warning. Thanks!

[xwu (Xiaodi Wu)]

@SDGGiesbrecht

I did however notice while tinkering that the importantArg _: Int variant breaks the parameter section of any inherited documentation (at least in Xcode). That should probably be fixed.

Right, this is the one issue with protocol conformances and subclasses that would cause problems here.

But: it's already a problem when a user (legitimately) wants to implement a protocol requirement but prefers alternative internal parameter names than those given by the protocol. For instance, in the Swift standard library, several of the SIMD implementations of binary operators required by protocols were changed to name the operands a and b, instead of lhs and rhs, to standardize with other binary operator implementations that aren't protocol requirements. Any inherited documentation inherited from a protocol is now broken.

This is a tooling bug, and it's the tail wagging the dog to try to "solve" this by contorting the design of a language feature.

@typesanitizer

Spelling-wise, if we used a spelling _parameterName instead of _ , that gives the reader a clue as to what the thing is supposed to be.

This wouldn't address the problem regarding protocol conformances by itself, since _parameterName is still different from parameterName, just as _ is. We need to teach the tooling to understand that implementations can inherit protocol documentation and match up the arguments by position to behave correctly to support _, and if it does that, then the _parameterName workaround wouldn't be necessary.

I see your point about telling the user something about what the _ is, but I think that can be accomplished in the tooling itself by, for example, numbering unnamed parameters in the generated documentation rather than privileging "magic" underscores in this one place. We already number unnamed parameters in closures, so the same syntax in documentation could be intuitive here.

Swift, which started off eschewing the punctuation-heavy syntax of Objective-C as a major attraction to users, has already acquired or expanded the use of a bunch of sigils like \ and $ and @ that prefix names. Used judiciously, sigils can be powerful, but I don't think this problem rises to one that could justify a solution that endows yet another sigil with additional special meaning instead of relying on existing syntax.

[xwu (Xiaodi Wu)]

@typesanitizer

When I was working on a Swift side-project a few weeks back, I hit two places where this would've helped me within the span of 1 week:

1. I updated a protocol method to take more arguments, but forgot to use all the arguments in one of the implementations.
2. I had a hard-coded value in a method. → I added an accidentally unused parameter with a default value matching the hard-coded value, and forgot to delete the hard-coded value. → I forgot to test the non-default case. → Hit the bug a few days later while investigating another bug.

This empiric evidence is so key to motivating this: in the draft implementation, the core team indicated that adding diagnostics for stylistic purposes isn't desirable: it is extremely useful to show (as the bug that motivated this thread and your examples do) that there are actual, real-world bugs that are mitigated by this diagnostic. That is very strong evidence to favor making a change.

[SDGGiesbrecht (Jeremy David Giesbrecht)]

@xwu

Right, this is the one issue with protocol conformances and subclasses that would cause problems here.

I did not consider it to be a problem with the pitch. I could find no problems. The bug is just something I stumbled on while toying with it, and which should presumably be fixed regardless of the pitch.