Example for Documentation?

[Steven Schveighoffer via Digitalmars-d]

On 4/21/15 11:25 AM, "Marc =?UTF-8?B?U2Now7x0eiI=?= <schuetzm at gmx.net>" 
wrote:
> 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.

quoted lambdas are indeed shorter, but the issue with them is that "a<b" 
instantiates a different template than "a < b", whereas the lambda does not.

In fact, that is why we added shorthand lambdas to the language. Note 
that in this case, it's just wasted code space and not a real issue. but 
for example, RedBlackTree!(int, "a < b") is not compatible with 
RedBlackTree!(int, "a<b"), even though they are identical.

I'm not saying we shouldn't allow string lambdas, just that we shouldn't 
encourage them as "proper" D code.

>> 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.

This use case seems niche to me. I haven't ever had the need to "sort" 
an AA, and if I did, I would use a RedBlackTree.

Not discounting it, or saying it's not valid or useful, just that it's 
not such a perfect example that it needs to unseat the current example 
(sorting points by x and y).

It definitely does not belong in the AA documentation.

-Steve