Example for Documentation?

[Chris via Digitalmars-d]

On Tuesday, 21 April 2015 at 14:25:29 UTC, Steven Schveighoffer 
wrote:
> On 4/21/15 10:07 AM, Chris wrote:
>> Here's bearophile's version of sorting an AA by value [1]
>>
>> void main() {
>>     import std.stdio: writeln;
>>     import std.algorithm.sorting: multiSort;
>>     import std.array: array;
>>
>>     const size_t[string] wCount = [
>>         "hamster": 5,
>>         "zorro": 80,
>>         "troll": 90,
>>         "algorithm": 80,
>>         "beer": 80
>>     ];
>>
>>     auto pairs = wCount.byKeyValue.array;
>>     assert(wCount.length == pairs.length);
>>     pairs.multiSort!(q{a.value > b.value}, q{a.key < b.key});
>>     assert(pairs[2].key == "beer");
>>     foreach (const ref it; pairs)
>>         writeln(it.key, ": ", it.value);
>> }
>>
>> Should we add it to the documentation of
>>
>> 1. 
>> http://dlang.org/phobos/std_algorithm_sorting.html#.multiSort
>> 2. http://dlang.org/hash-map.html
>
> We should not be promoting string-based lambdas:
>
> pairs.multiSort!((a, b) => a.value > b.value, (a, b) => a.key < 
> b.key);
>
> I think this would be a perfect addition for the disqus forum 
> of that function (once ddox gets to be the default). I don't 
> want to get into adding sample usages for every use case on 
> every function to the documentation.
>
> -Steve

Not for every use case, but multiSort is the perfect match for 
sorting AAs, isn't it? I suggested to add it, because it is a) 
useful and b) one of _the_ use cases of multiSort.

The current example in the documentation is ok, but adding how to 
sort AA would be useful. Also, multiSort is not even mentioned in 
the cheat sheet section. Given that it does more or less what 
spread sheets can do, it might be of interest to people who work 
a lot with stats and numbers and that kinda stuff.