Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[SR-13757] Dictionary subscript(_:default:) summary is wrong and subscript(_) summary is weak. #56154

Closed
dabrahams opened this issue Oct 20, 2020 · 3 comments
Closed

[SR-13757] Dictionary subscript(_:default:) summary is wrong and subscript(_) summary is weak. #56154

dabrahams opened this issue Oct 20, 2020 · 3 comments
Labels
bug A deviation from expected or documented behavior. Also: expected but undesirable behavior. documentation standard library Area: Standard library umbrella

Comments

@dabrahams
Copy link
Collaborator

Previous ID SR-13757
Radar rdar://problem/70543419
Original Reporter @dabrahams
Type Bug
Status Resolved
Resolution Done
Additional Detail from JIRA
Votes 0
Component/s Standard Library
Labels Bug, Documentation
Assignee amartini (JIRA)
Priority Medium

md5: 3a37feea68ce7ff1e559a3ba24a3bc5a

Issue Description:

The summary says:

Accesses the value with the given key. If the dictionary doesn’t contain the given key, accesses the provided default value as if the key and default value existed in the dictionary.

This omits the fact that the key and the default are inserted if the key doesn't already exist. Also doesn't follow DevPubs' own guideline—replicated for the Swift API guidelines—that the summary should be a sentence fragment. Corrected phrasing:

Accesses the value for the given key or the provided default no such key exists in the dictionary, on write first inserting the key with the provided default value if it does not exist in the dictionary.

This error has real consequences; it caused me to report SR-9870 as impossible rather than merely awkward, and I'm sure most other people would give up sooner than I did.
@dabrahams
Copy link
Collaborator Author

I notice the optional-returning subscript is… if not wrong, then very weak, as it doesn't describe the special role of `nil` or the ability to cause the key to be deleted. Certainly, “for writing” adds nothing here as the declaration clearly includes a setter. This would fix it:

Accesses the value associated with the given key, producing `nil` when the value of a key not in the dictionary is read, and erasing the key if `nil` is written.

Oh, my. Code voice is disallowed in summaries by DevPubs, IIRC? How on earth are you supposed to talk about nil without code voice?

@typesanitizer
Copy link

@swift-ci create

@swift-ci
Copy link
Collaborator

Comment by Alex Martini (JIRA)

Fixed in cc708f8.

#36709

@swift-ci swift-ci transferred this issue from apple/swift-issues Apr 25, 2022
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug A deviation from expected or documented behavior. Also: expected but undesirable behavior. documentation standard library Area: Standard library umbrella
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@dabrahams @typesanitizer @swift-ci