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

Reply via email to