docs: Specify that common sort functions sort in an ascending direction

[Natr1x]

From forum discussion it seems like the sorting direction can be expected to always be ascending (in terms of cmp::Ordering).

If this is the case then it would be nice to have this stated in the documentation.

[rustbot]

r? @joboet

rustbot has assigned @joboet.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[workingjubilee]

@Natr1x As long as we're being excruciatingly explicit, should we note that "ascending" here causes slice::first to be the least and slice::last to be the greatest according to the Ordering? Or that the index order of values also compares like their comparison order, if you prefer (the least index, 0, is now the least value, et cetera).

...I say this because I have gotten confused before when "ascending" and "descending" flew around in a conversation that involved multi-part or "reversed" keys such that both "directions" lacked an obvious meaning. For bonus fun, at that point in a conversation, sometimes people will talk about the sorted ordering being "descending" when they have used such a sorting function to sort things into the ascending order of a reversed key.

[Natr1x]

@workingjubilee

I considered it. But I think the examples already explain this, and the extra clutter may just make it harder to read and thus more confusing.

The biggest reason I wanted to add this was to clarify that the order direction is consistent and expected to stay the same.

[workingjubilee]

cool! yeah, "the examples already cover that" seems like a good reason for allowing the code to be the extra explanation since the code is... extra explanation. I still wonder if we should talk more about it, but we can explore that in other ways another day.

seems fine to me then.