Clarify docs for flip (#271)

* Clarify docs for `flip`

* Keep previous but altered example

Author: JordanMartinez

CHANGELOG.md

@@ -12,6 +12,7 @@ Bugfixes:
 
 Other improvements:
 - Changed `unit`'s FFI representation from `{}` to `undefined` (#267 by @JordanMartinez)
+- Clarify docs for `flip` (#271 by @JordanMartinez)
 
 ## [v5.0.1](https://github.com/purescript/purescript-prelude/releases/tag/v5.0.1) - 2021-05-11
 

src/Data/Function.purs

@@ -13,10 +13,15 @@ import Data.Boolean (otherwise)
 import Data.Ord ((<=))
 import Data.Ring ((-))
 
--- | Flips the order of the arguments to a function of two arguments.
+-- | Given a function that takes two arguments, applies the arguments
+-- | to the function in a swapped order.
 -- |
 -- | ```purescript
--- | flip const 1 2 = const 2 1 = 2
+-- | flip append "1" "2" == append "2" "1" == "21"
+-- |
+-- | const 1 "two" == 1
+-- |
+-- | flip const 1 "two" == const "two" 1 == "two"
 -- | ```
 flip :: forall a b c. (a -> b -> c) -> b -> a -> c
 flip f b a = f a b