swift

89ca059b - Fix link and parameter documentation errors in Swift stdlib source (#89911)

Fix link and parameter documentation errors in Swift stdlib source (#89911) rdar://172117819 (Fix link and parameter documentation errors in Swift stdlib source) While working on #88061, I found about 300 DocC errors in the stdlib source doc comments, which show up as warnings when building the docs with `docc`, and results in incomplete documentation. The problems generally fall into a few common groups: * **Incorrect parameter name**: These occur when a DocC `- Parameter:` tag uses a name different from what's in the signature (for example, using `lhs` and `rhs` to document an `=(_:_:)` operator that actually names its parameters `a` and `b`), or it uses the outer name rather than the inner name. * **Out-of-module links**: DocC can only create links within a symbol's module. The standard library is actually a collection of several modules, with most of what we think of as the stdlib in `core`, but there's also important stuff in `concurrency`, `observation`, etc. And the within-own-module rule means that, for example, docs on `Actor` can't create double-backtick links to `Hashable`, because that's attempting to link from `concurrency` to `core`. I've generally just demoted these to code-voice. * **Link disambiguation**: If a given symbol has many overloads, DocC uses a [disambiguation syntax](https://www.swift.org/documentation/docc/linking-to-symbols-and-other-content#Ambiguous-Symbol-Links) to distinguish between versions with different parameter types, generic conformances, etc. In cases where there was a clear intent to link to a specific version, I added the most appropriate disambiguation link. In other cases, particularly where a doc might be speaking generally to any relevant flavor of a `doFoo()` method, I demoted the link to code voice, since there isn't a "right" disambiguation to choose in these cases. * **Parameters to closures**: DocC has no syntax for cases where a closure parameter itself takes one or more parameters. Generally, the safest approach is to describe these parameters in the documentation of the closure parameter, and this is the only option when the parameter isn't named. In cases where the parameter is named (like `buffer` in the trailing closure for several flavors of `withMemoryRebound()`), @d-ronnqvist suggested using the DocC term list syntax to give the secondary parameter a slight indentation, which is probably what the original author would have wanted. I'm adding the following people as reviewers just so they're aware I'm stomping around in their code: * @ktoso (distributed, runtimemodule) * @phausler (observation) * @al45tair and @carlpeto (runtimemodule - Carl may have just done the DocC formatting) * @Azoy (atomics, ref) * @jmschonfeld (range) * @natecook1000 (range) * @airspeedswift (set) * @glessard (rawspan) * @milseman (string.index) This PR only changes comments, not declarations or code.