Name the documented arguments the way the declarations name them

[karpovantonme]

Motivation:

Eight doc comments name an argument that the declaration below them does not have, so DocC has nothing to bind the description to and quietly drops it. Nothing warns about this: Swift has no equivalent of -Wdocumentation, and DocC stays silent rather than complaining, so these sit until somebody reads the generated page and wonders where the description went

file	the comment says	the declaration says
NIOPosix/ServerSocket.swift	descriptor	socket
NIOPosix/Socket.swift ×2	descriptor	socket
NIOHTTP1/ByteCollectionUtils.swift	bytes	to
NIOHTTP1/HTTPTypes.swift	buffer	headers
NIOFS/BufferedStream.swift ×2	sequence	element
NIOFS/SystemFileHandle.swift	executor	threadPool

The socket ones are worth a word. Each of those files has a pair: a deprecated init(descriptor:) and its replacement init(socket:), and the rename is recorded right there in @available(*, deprecated, renamed: "init(socket:setNonBlocking:)"). The replacement inherited the wording of the one it replaced, so the doc still says descriptor. The deprecated ones are correct and I left them alone

And the last two are the same defect in two copies of one module, NIOFS and _NIOFileSystem, which is what a verbatim copy of a file does to a mistake inside it. Fixing one and not the other would leave them out of sync, so both are in here

Modifications:

Renamed the documented argument to the one in the declaration, eleven lines across eight files

One is slightly more than a rename: in ByteBuffer.write(headers:) the entry described the buffer the method is called on rather than its argument, so it now describes headers and keeps the note about the writer index

Result:

The parameter descriptions reach the generated documentation. No API change, no behaviour change, comments only

btw these came out of a checker I wrote for exactly this, run over the tree and then read by hand one by one. Six of the things it flagged turned out to be my parser rather than your code, and those are fixed on my side rather than sent to you 🙌🏼

all of it on a MacBook Air M3, of course

[glbrntt]

Great, thank you!