@@ -228,15 +228,41 @@ drop = Native.List.drop
228228repeat : Int -> a -> [a]
229229repeat = Native.List.repeat
230230
231−{-| Sort a list in ascending order. -}
231+{-| Sort values from lowest to highest: `sort [3,1,5] == [1,3,5]`
232+-}
232233sort : [comparable] -> [comparable]
233234sort = Native.List.sort
234235
235−{-| Sort a list by a given comparison transformation, such a [record field
236−accessors](http://elm-lang.org/learn/Syntax.elm#records). -}
236+{-| Sort values by a derived property.
237+
238+```haskell
239+alice = { name="Alice", height=1.62 }
240+bob = { name="Bob" , height=1.85 }
241+chuck = { name="Chuck", height=1.76 }
242+
243+sortBy .name [chuck,alice,bob] == [alice,bob,chuck]
244+sortBy .height [chuck,alice,bob] == [alice,chuck,bob]
245+
246+sortBy String.length ["five","hi"] == ["hi","five"]
247+```
248+-}
237249sortBy : (a -> comparable) -> [a] -> [a]
238250sortBy = Native.List.sortBy
239251
240−{-| Sort a list by a given comparison function. -}
252+{-| Sort values with a custom comparison function.
253+
254+```haskell
255+sortWith flippedComparison [1..5] == [5,4,3,2,1]
256+
257+flippedComparison a b =
258+ case compare a b of
259+ LT -> GT
260+ EQ -> EQ
261+ GT -> LT
262+```
263+
264+This is also the most general sort function, allowing you
265+to define any other: `sort == sortWith compare`
266+-}
241267sortWith : (a -> a -> Order) -> [a] -> [a]
242268sortWith = Native.List.sortWith