maximumBy and minimumBy documentation could use a little work

[Chadtech]

@rlefevre opened up #109 recently, and I had to look into what maximumBy and minimumBy do. I felt like the documentation was a little confusing. Like the term 'first maximum' was unintuitive to me. I guess theres no reason you couldnt have multiple maximums (if the two maximum are equal and above all the others) but its not a part of the normal connotation.

Then also, there are no code examples for these functions. There should be.

Is it just me that finds the documentation on these lacking? I dont really want to go off and fix these things up if its just me.

[rlefevre]

There could be several maximums, but then the function should return a List a, so the first maximum was quite clear to me, for example:

> maximumBy .val [{id=1, val=1}, {id=2, val=2}, {id=3, val=2}]
Just { id = 2, val = 2 }
    : Maybe { id : number1, val : number }

where the last two elements have the same value.

But you may be right, it could be better to return a list then to use List.head to get the "first" maximum. Maybe we could have maximums and maximum.

[Chadtech]

Oh I didnt even think about returning a list of maximums. Thats interesting. I just meant it could be phrased better. Like I would write "It returns the maximum, if there are two maximums it returns the first one" or something. In the first clause of the sentence it says what it does in the simplest and most intuitive way, in the second clause, the sentence covers this edge case thats not immediately obvious.