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

sort: Sort documentation should describe most common sort order #48527

Closed
kevinburke opened this issue Sep 21, 2021 · 2 comments
Closed

sort: Sort documentation should describe most common sort order #48527

kevinburke opened this issue Sep 21, 2021 · 2 comments
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.

Comments

@kevinburke
Copy link
Contributor

The docstring for sort.Sort says:

// Sort sorts data.
// It makes one call to data.Len to determine n and O(n*log(n)) calls to
// data.Less and data.Swap. The sort is not guaranteed to be stable.

It would be nice if this explained which order data is returned in. I understand that you can call sort.Sort(sort.Reverse(data)), or provide a Less() function that returns true if i is greater than j, but we could provide some guidance about what is most likely to happen.

For example:

// Sort sorts data.
// It makes one call to data.Len to determine n and O(n*log(n)) calls to
// data.Less and data.Swap. The sort is not guaranteed to be stable.
// Usually, the lowest value will be sorted first. Use Reverse to sort the
// highest value first.
func Sort(data Interface) {

Instead of "Usually", could also consider "By default", "When used with the methods in this package", etc.

@ianlancetaylor
Copy link
Contributor

If we say anything here--I'm not sure we need to--we should just say "The result is sorted in ascending order according to the Less method."

@gopherbot
Copy link

Change https://golang.org/cl/351336 mentions this issue: src/sort: improve sort documentation

@dr2chase dr2chase added the NeedsFix The path to resolution is known, but the work has not been done. label Sep 24, 2021
@golang golang locked and limited conversation to collaborators Nov 16, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

4 participants