[SortedCollections] Name the documented arguments the way the declarations name them - #705
Open
karpovantonme wants to merge 1 commit into
Open
[SortedCollections] Name the documented arguments the way the declarations name them#705karpovantonme wants to merge 1 commit into
karpovantonme wants to merge 1 commit into
Conversation
…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.
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.
#701 covers the shipping modules. This is the same thing in
SortedCollections, which sits behind theUnstableSortedCollectionstrait and so is not in a default build17 doc comments here name an argument that the declaration below them does not have, mostly renames the comment did not follow:
SortedDictionary.Keysand.Valuescarry 8 blocks documenting- Parameter iwhile every one of those declarations takesindex_Node.UnsafeHandledocumentsnewHandlewhere the argument istarget, andnewElementwhere it isnewChild_Node.Splinterdocumentsnode, the initializer takesleftChild_BTree.Indexdocumentsindex, the initializer takesoffset_BTree+UnsafeCursordocumentskeywheretakeCursor(at:)takesindexWhere a
- Returnsline carried the old name too, it came along, so each block reads consistently.index(after:)andindex(before:)inKeysandValuesreturned "the index immediately afteri", andtakeCursor(at:)returned "a cursor to the key or where the key should be inserted", which is the other overload's behaviourThe
iin the neighbouring blocks is left alone on purpose:index(after i:),formIndex(_ i:)andindex(_ i:, offsetBy:)really are named that, and only these overloads were renamed without the comments followingOne block is removed rather than renamed.
_BTree.swiftdocuments "a path to the key at absolute offset" with- Parameter offset,- Returnsand- Complexity, then comes a blank line and then the doc comment forstartIndex(forKey:), so it binds to nothingComments only, no API change. Fine by me to close it if you would rather leave this module alone
Checklist