Verbose or shorter stdlib crystal docs preferred

Hmm

Yeah there has been a small amount of earlier discussion:

Here’s the situation:

Imagine I get an array of…instances coming out of a database query in a certain initial order given by the query. I want to have the initial order be my secondary ordering, so I sort_by to introduce a new primary ordering, while retaining the secondary ordering that the array started with.
If sort_by isn’t stable, any chained sort_by jumbles all previous ordering.
So for sort_by at least, it feels like it should be default stable or it can lead to…unanticipated behavior. This is how Rust does it (though Go doesn’t).
It seems to me that people that “don’t care, give me something sorted” might prefer a stable sort (fewer surprises, easier for beginners), unless they are really going for speed, in which case they might prefer an unstable sort.

For the other sort methods, it might not be intuitive that unstable by default means that comparisons that report “equal” are possible to result in a scrambled order, as well. https://github.com/crystal-lang/crystal/issues/6057#issuecomment-605584525

See also Poll: should default sort behavior be "fast" or "stable"?

So overall it seems to me like unstable_sort should be kind of an opt-in “you know what you’re getting in to” type of thing?

So maybe I can propose the addition of unstable_sort methods, for the reasons above, thoughts?

Thanks,

-Roger-