search

elm-community / list-extra

Convenience functions for working with List.
http://package.elm-lang.org/packages/elm-community/list-extra/latest
MIT License
135 stars 59 forks source link

Minor updates to docstrings, clarification for `groupWhile` #74

Closed tac-tics closed 7 years ago

tac-tics commented 7 years ago

There was a minor typo calling the test for groupWhile an "equivalent relationship". I changed it to "equivalence relation" and wrote out a bit more explicitly for programmers what that means.

I threw in a few minor grammatical changes.

Chadtech commented 7 years ago

What do you mean by "it will give an unexpected answer [ if its not an equivalence relation ]". Its a deterministic process, so the answer follows from the code and the input right? Do you mean the answer is arbitrary or just not useful?

pzp1997 commented 7 years ago

I interpret it to mean that this behavior is subject to change and should not be relied upon. (Perhaps that phrasing is clearer?) It's also worth noting that there's a somewhat ongoing discussion about getting rid of the non-transitive version of this function in #45.

tac-tics commented 7 years ago

@pzp1997 That is essentially what I was getting at.

The main goal of the patch I made was to clean up the explanation for "equivalence relation". But I figured if so much emphasis would be placed on using it in this way (arguably the "correct way"), rather than explain how it works in the non-equivalence relation case, it's best to gently push the user away from doing that.

Also, just parsing the documentation was causing me confusion (knowing full well what an equivalence relation is :smile:) because it showcased groupBy (<) [...] in a code block. Seeing it in a box made it originally seem like "here's an example of how to use it" when in fact that's not how you ever want to use it.