Name the documented arguments the way the declarations name them - #701
Open
karpovantonme wants to merge 1 commit into
Open
Name the documented arguments the way the declarations name them#701karpovantonme wants to merge 1 commit into
karpovantonme wants to merge 1 commit into
Conversation
Twenty-five doc comments in the shipping modules 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. Most of them are renames that the comment did not follow, and the file itself usually holds the proof: RigidDeque.prepend says - maxCount while its own Complexity line already says newItemCount, and append(copying:) has three overloads where the oldest still takes newElements and the two newer ones take items with the older one's wording. Three entries name an argument that no longer exists at all and are removed rather than renamed.
karpovantonme
added a commit
to karpovantonme/swift-collections
that referenced
this pull request
Aug 16, 2026
…tions name them Same species as apple#701, in the module behind the UnstableSortedCollections trait. 16 doc comments name an argument the declaration does not have, and one block documents a function that is no longer there. The Keys and Values views carry the same four each: - Parameter i where the argument is index, and - Parameter index on subscript(position:). In the B-tree internals the descriptions usually name the right thing while the key does not: - node on toNode(leftChild:) says the argument becomes the left child, and - newElement on exchangeChild(atSlot:with newChild:) says it is the new child. _BTree.swift keeps a doc block for a function that was removed: it documents an offset parameter and sits above an unrelated declaration.
karpovantonme
added a commit
to karpovantonme/swift-collections
that referenced
this pull request
Aug 16, 2026
…tions name them Same species as apple#701, in the module behind the UnstableSortedCollections trait. 16 doc comments name an argument the declaration does not have, and one block documents a function that is no longer there. The Keys and Values views carry the same four each: - Parameter i where the argument is index, and - Parameter index on subscript(position:). In the B-tree internals the descriptions usually name the right thing while the key does not: - node on toNode(leftChild:) says the argument becomes the left child, and - newElement on exchangeChild(atSlot:with newChild:) says it is the new child. _BTree.swift keeps a doc block for a function that was removed: it documents an offset parameter and sits above an unrelated declaration.
7 tasks
lorentey
approved these changes
Aug 18, 2026
lorentey
left a comment
lorentey
left a comment
Member
There was a problem hiding this comment.
Thank you for fixing all these! 👍
Member
|
The failing check is due to a CI issue; #706 will eventually resolve it. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
25 doc comments in the shipping modules 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 complainingMost are renames the comment did not follow, and the file itself usually holds the proof:
RigidDeque.prependdocuments- maxCountwhile its own- Complexity: O(newItemCount ?? self.freeCapacity)two lines below already uses the new nameRigidArray.append(copying:)has 3 overloads. The oldest takesnewElementsand its comment is right; the 2 newer ones takeitemsand carry the older one's wordingBitArray.index(after:)writes the name in backticks, which DocC does not bind either, and the argument isi. Two functions below,formIndex(after i:)gets it right3 entries name an argument that no longer exists at all rather than a renamed one, so they are removed instead:
stoppingOnFirstDuplicateValueonfill(untilFirstDuplicateIn:)andduplicateson the two_HashTable.createoverloads, where the behaviour now lives in the function namewhere a description or a
- Complexity:line referred to the old name too, it was brought along, so each block reads consistentlySortedCollectionsis left out on purpose: it sits behind theUnstableSortedCollectionstrait and has 17 more of these, which felt like a separate conversation. Happy to send that as its own PR if you want itOne I left alone:
UniqueArray.nextSpan(after:)documentsmaxCount, but the whole block looks copied from thenextSpan(maxCount:after:)overload, and I could not tell whether you would rather drop the entry or the blockComments only, no API change
btw these came out of a checker I wrote for exactly this, run over the tree and then read one by one. 6 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
Checklist