Example for Documentation?

[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 find the strings to be more readable, simply because they are 
shorter. I would probably even prefer normal "" quotes.

Compare:

pairs.multiSort!((a, b) => a.value > b.value, (a, b) => a.key < 
b.key);
pairs.multiSort!(q{a.value > b.value}, q{a.key < b.key});
pairs.multiSort!("a.value > b.value", "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.

Not for every possible use case, but I'd prefer examples 
demonstrating an actual, practical application to ones that were 
just made up for the sake of documentation.