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

[SR-7512] Documentation omits required conformances #50054

Open
NevinBR opened this issue Apr 24, 2018 · 5 comments
Open

[SR-7512] Documentation omits required conformances #50054

NevinBR opened this issue Apr 24, 2018 · 5 comments
Labels
improvement standard library Area: Standard library umbrella

Comments

@NevinBR
Copy link
Contributor

NevinBR commented Apr 24, 2018

Previous ID SR-7512
Radar None
Original Reporter @NevinBR
Type Improvement
Status Reopened
Resolution
Additional Detail from JIRA
Votes 0
Component/s Standard Library
Labels Improvement
Assignee None
Priority Medium

md5: c68ce4065abf48d06f2d4c130d172c61

Issue Description:

The MutableCollection methods sort() and sort(by:) are constrained to require RandomAccessCollection conformance. However, the documentation for them makes no mention of RandomAccessCollection. That documentation should be improved to include the constraints on their availability.

@belkadan
Copy link
Contributor

belkadan commented May 1, 2018

That sounds like an issue with Apple's docs rather than with anything in the Swift Open Source project. Can you file this at https://bugreport.apple.com instead?

@NevinBR
Copy link
Contributor Author

NevinBR commented May 1, 2018

The text of Apple’s documentation appears to be taken verbatim from the doc-comments on the sort() methods, as found in stdlib/public/core/CollectionAlgorithms.swift

Here is the Comparable version, and here is the version that takes a closure.

Note in particular that the doc-comment for the Comparable version of sort() states near the top, “You can sort any mutable collection of elements that conform to the `Comparable` protocol by calling this method.”

That is clearly incorrect, because the method is inside an extension constrained to RandomAccessCollection. I am reopening this because it is a standard-library documentation issue.

I can go ahead an submit a PR to fix the documentation, unless someone else is in charge of that.

@belkadan
Copy link
Contributor

belkadan commented May 1, 2018

Ah, sure, changing the doc text is covered by this, and a PR is definitely welcome. It's still worth filing a Radar, though, so that the Apple docs page can include the constraints on the method and not just its enclosing protocol.

@belkadan
Copy link
Contributor

belkadan commented May 1, 2018

It's not generally the responsibility of a doc comment to repeat the constraints that are already in the declaration, but it shouldn't get them wrong.

@ole
Copy link
Contributor

ole commented Jun 10, 2018

I filed Radar 40980314 for the Apple documentation issue. I used the new shuffle method as the primary example but I also mentioned sort. The issue is the same in both cases.

@swift-ci swift-ci transferred this issue from apple/swift-issues Apr 25, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
improvement standard library Area: Standard library umbrella
Projects
None yet
Development

No branches or pull requests

3 participants