[SR-12842] Missing documentation for RangeExpression.~= operator

[gwynne]

Previous ID	SR-12842
Radar	rdar://problem/65491491
Original Reporter	@gwynne
Type	Bug

Additional Detail from JIRA

Votes	0
Component/s	Standard Library
Labels	Bug, Documentation
Assignee	None
Priority	Medium

md5: 28e3f3762560fc35287695704135bdfd

Issue Description:

The commit 3890376 in early 2017 appears to have been partially responsible (inasmuch that it's the closest I could get to the real culprit easily, since GitHub's History and Blame interfaces don't follow file renames seemingly at all) for the accidental removal of the headerdoc comments covering the ~= operator for the various forms of Range. The missing documentation apparently went unnoticed when the operator was later reimplemented in an extension on RangeExpression. Thanks to this, there's no visible documentation for the operator's behavior at all right through to present day, at least none that I could find.

[gwynne]

This bothered me a lot - I didn't even remember there was such an operator until I chanced on someone else's code using it in the appropriate context. IMO this says a lot about the role availability of visible documentation plays in developer awareness of functionality in the standard library. And since adding documentation comments entails very little risk of breakage, as far as I know, I think this is worth assigning a high priority. It'd be awesome if the fix could still get into Swift 5.3. I'll open a PR to add back a slightly revised version of the original documentation momentarily.

[gwynne]

#31907 (master)
#31908 (5.3)

[airspeedswift]

@swift-ci create