Skip to content

Name the documented arguments the way the declarations name them - #3698

Merged
glbrntt merged 1 commit into
apple:mainfrom
karpovantonme:doc/parameter-names
Sep 1, 2026
Merged

glbrntt merged 1 commit into
apple:mainfrom
karpovantonme:doc/parameter-names

Conversation

@karpovantonme

Copy link
Copy Markdown
Contributor

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 glbrntt added the semver/none No version bump required. label Aug 13, 2026

@glbrntt glbrntt left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great, thank you!

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 drops it. Nothing
warns about this: Swift has no equivalent of -Wdocumentation, and DocC stays
silent rather than complaining.

Three of them 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 in
it.

Modifications:

Renamed the documented argument to the one in the declaration, in eleven
places across eight files. In ByteBuffer.write(headers:) the entry described
the buffer the method is called on rather than the argument, so it now
describes the argument and keeps the note about the writer index.

The deprecated init(descriptor:setNonBlocking:) overloads were left alone:
their documentation is correct. It is their replacements, init(socket:), that
inherited the wording.

Result:

The parameter descriptions reach the generated documentation. No API change,
no behaviour change, comments only.
auto-merge was automatically disabled September 1, 2026 02:58

Head branch was pushed to by a user without write access

@glbrntt
glbrntt enabled auto-merge (squash) September 1, 2026 05:17
@glbrntt
glbrntt merged commit 14059d6 into apple:main Sep 1, 2026
106 of 115 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

semver/none No version bump required.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants