Better docs for D (WIP)

[Andrei Alexandrescu via Digitalmars-d-announce]

On 01/05/2016 10:15 AM, bachmeier wrote:
>
> I read the documentation for schwartzSort, and finding that it conveyed
> no information, I wanted to suggest something better. A discussion forum
> or email message would be the ideal way to do so, but knowing that's not
> how things are done here, I decided to submit a PR. After at least a
> couple hours (it may have been more) looking at other documentation to
> find ideas for how to do it better, doing several revisions to get to
> something I found satisfactory, checking for no trailing spaces and
> making sure the syntax was consistent with the other documentation,
> battling with Git, and battling to get the full site to build, I
> submitted this:
>
> https://github.com/D-Programming-Language/phobos/pull/3831
>
> One person reviewed it and didn't like my change, because he felt the
> existing documentation was better. Later, someone commented that he
> liked my version. And now it's sitting there. It's not going to be
> accepted and because nobody's in charge of the documentation it won't be
> closed either.

Thanks for submitting. The way I see it is that PR needs improvement. 
The bar is low seeing as pretty much any addition to the documentation 
is good. So all you need to do is make sure the addition is of good quality.

So the proposed final text is:

============
Returns the same output as an equivalent call to $(D sort), but it will be
faster when the sort comparison requires an expensive computation.
$(D schwartzSort) allocates a temporary array to cache the sort keys. It 
can
therefore be slower than $(D sort) in other cases.

Sorts a range using an algorithm akin to the $(WEB
wikipedia.org/wiki/Schwartzian_transform, Schwartzian transform), also
known as the decorate-sort-undecorate pattern in Python and Lisp. The
complexity is the same as that of the corresponding $(D sort), but
$(D schwartzSort) evaluates $(D transform) only $(D r.length) times 
(less than
half when compared to regular sorting). The usage can be best 
illustrated with
an example.
=============

The text is imprecise, e.g. an equivalent call to `sort` really is 
`sort!((a, b) => less(transform(a), transform(b))`. All that detail 
needn't be present in the first paragraph, so there's a bit of an art in 
how you formulate simple sentences that are at the same time correct and 
informative.

The second paragraph used to be the first (and only) one. Now it doesn't 
flow from the first one, it's jarring. Here's a possible improved text 
(feel free to copy, paste, adapt etc):

============
Alternative sorting method that should be used when comparing keys 
involves an expensive computation. Instead of using `less(a, b)` for 
comparing elements, `schwartzSort` uses `less(transform(a), 
transform(b)`. The values of the `transform` function are precomputed in 
a temporary array, thus saving on repeatedly computing it. Conversely, 
if the cost of `transform` is small compared to the cost of allocating 
and filling the precomputed array, `sort` may be faster and therefore 
preferable.

This approach to sorting is akin to the $(WEB
wikipedia.org/wiki/Schwartzian_transform, Schwartzian transform), also
known as the decorate-sort-undecorate pattern in Python and Lisp. The
complexity is the same as that of the corresponding $(D sort), but
$(D schwartzSort) evaluates $(D transform) only $(D r.length) times 
(less than half when compared to regular sorting). The usage can be best 
illustrated with an example.
=============

> The problem is not that my PR was (for practical purposes) rejected. As
> an academic I deal with both sides of peer review all the time. The
> problem is that I was forced to put so much time into it just to make a
> suggestion. With Adam's project, I can send him an email with a
> suggested change, and he can do as he wishes with it. It will take two
> minutes of my time.

I agree that the best aspect of Adam's system is Adam.


Andrei