[saagarjha]

I mean you're going to tell me that this a rehash of what the Stack Overflow people told you but the reason this is a warning is because the external name is meant to aid in readability but the internal name is the one that is actually operated on, so the latter is the one that is actually relevant when documenting what the thing actually is. It would be unreasonable to write documentation for a parameter called "in" (internal name: range) or "behind" (internal name: window). So yeah, you're holding it wrong. If you disagree you should do one of two things:

1. Ask for a way to use the external name as documentation. (This is not a serious suggestion, because if you go do this people will laugh at you and tell you to stop doing that. But you could do it.)

2. Ask for a way to turn off warnings. (This is a reason suggestion, I actually want this. Unfortunately the answer that you really want is "no you can't do this".)

[ChrisMarshallNY]

Yeah, you can look at it that way, but API documentation is for external users, and I prefer to reduce the number of inline comments, inside the function, which is not where the external users will be going, anyway.

Most folks will only care about the external name. The internal name is for maintainers. It not only indicates the value is a constant, it also tells you that it has not been altered since entering the function body, and that's pretty important. The "in" prefix regularly saves me from assigning the unprocessed value, instead of one that has had some conditioning applied.

No matter. As long as the warning doesn't bork the build, I can live with it.

I could probably provide protocols for API documentation, but protocols have their own issues[0].

[0] https://littlegreenviper.com/the-curious-case-of-the-protoco...

[saagarjha]

I only skimmed this but you might be able to leverage @_implements here?