Fix wording around sort guarantees #38961
Conversation
There was a problem hiding this comment.
You changed the documentation of sort(), but forgot about sort_by and sort_by_key :)
The current changes will resolve the discussed normativity issue, which is good. However, I'd like to push for higher quality documentation while we're at it.
I left a few suggestions on how to do that. We don't need long boring walls of text. Just a few points on the key characteristics of this particular implementation.
| /// temporary storage half the size of `self`. | ||
| /// This sort is stable and `O(n log n)` worst-case. | ||
| /// | ||
| /// # Current Implementation |
There was a problem hiding this comment.
Just nitpicking here: lowercase "implementation" would be more consistent with other docs in libstd.
| /// | ||
| /// # Current Implementation | ||
| /// | ||
| /// The current implementation allocates temporary storage half the size of `self`. |
There was a problem hiding this comment.
Now that we have a section about the current implementation, this would be a great chance to expand a little bit. For inspiration, see Java's docs starting from "Implementation note".
I would like to see several things pointed out:
- That this sort is an adaptation of Tim Peters' timsort with this link.
- That this is an iterative sort.
- That this is an adaptive sort. Again, Java has a nice explanation: "It is well-suited to merging two or more sorted arrays: simply concatenate the arrays and sort the resulting array."
| @@ -1041,8 +1041,11 @@ impl<T> [T] { | |||
|
|
|||
| /// This is equivalent to `self.sort_by(|a, b| a.cmp(b))`. | |||
| /// | |||
| /// This sort is stable and `O(n log n)` worst-case, but allocates | |||
| /// temporary storage half the size of `self`. | |||
| /// This sort is stable and `O(n log n)` worst-case. | |||
There was a problem hiding this comment.
Let's explain what "stable" means, since it can be a confusing term for people unfamiliar with it.
Java's docs have a nice concise explanation: "This sort is guaranteed to be stable: equal elements will not be reordered as a result of the sort."
|
One more thing I noticed...
|
|
@brson @alexcrichton are we going to backport this? If so, I can wrap it up right now, but if not, I'd rather not drop everything to do so. know you wanted to get beta done by today |
|
I'd be ambivalent about a backport. I wouldn't advocate for it but I also wouldn't say no. |
|
@steveklabnik looks like there's a whitespace error here, but other than that r=me |
alexcrichton
added
the
T-libs-api
steveklabnik
force-pushed
the
fix-sort-wording
branch
from
6624105 to
e02f923
Compare
|
@bors: r+ |
|
📌 Commit e02f923 has been approved by |
Fix wording around sort guarantees Fixes #38524 /cc @rust-lang/libs @stjepang
|
☀️ Test successful - status-appveyor, status-travis |
Fixes #38524
/cc @rust-lang/libs @stjepang