diff --git a/src/Control/Apply.purs b/src/Control/Apply.purs index 9018b6f4..fba309a6 100644 --- a/src/Control/Apply.purs +++ b/src/Control/Apply.purs @@ -26,6 +26,15 @@ import Control.Category (identity) -- | the function application operator `($)` to arguments wrapped with the -- | type constructor `f`. -- | +-- | Put differently... +-- | ``` +-- | foo = +-- | functionTakingNArguments <$> computationProducingArg1 +-- | <*> computationProducingArg2 +-- | <*> ... +-- | <*> computationProducingArgN +-- | ``` +-- | -- | Instances must satisfy the following law in addition to the `Functor` -- | laws: -- | diff --git a/src/Control/Bind.purs b/src/Control/Bind.purs index 4257665f..b0aaaa44 100644 --- a/src/Control/Bind.purs +++ b/src/Control/Bind.purs @@ -63,6 +63,26 @@ infixr 1 bindFlipped as =<< instance bindFn :: Bind ((->) r) where bind m f x = f (m x) x +-- | The `bind`/`>>=` function for `Array` works by applying a function to +-- | each element in the array, and flattening the results into a single, +-- | new array. +-- | +-- | Array's `bind`/`>>=` works like a nested for loop. Each `bind` adds +-- | another level of nesting in the loop. For example: +-- | ``` +-- | foo :: Array String +-- | foo = +-- | ["a", "b"] >>= \eachElementInArray1 -> +-- | ["c", "d"] >>= \eachElementInArray2 +-- | pure (eachElementInArray1 <> eachElementInArray2) +-- | +-- | -- In other words... +-- | foo +-- | -- ... is the same as... +-- | [ ("a" <> "c"), ("a" <> "d"), ("b" <> "c"), ("b" <> "d") ] +-- | -- which simplifies to... +-- | [ "ac", "ad", "bc", "bd" ] +-- | ``` instance bindArray :: Bind Array where bind = arrayBind diff --git a/src/Control/Monad.purs b/src/Control/Monad.purs index 36c7311a..03e01bef 100644 --- a/src/Control/Monad.purs +++ b/src/Control/Monad.purs @@ -31,6 +31,7 @@ import Data.Unit (Unit) class (Applicative m, Bind m) <= Monad m instance monadFn :: Monad ((->) r) + instance monadArray :: Monad Array -- | `liftM1` provides a default implementation of `(<$>)` for any diff --git a/src/Data/Monoid.purs b/src/Data/Monoid.purs index 6ffa614d..2be6640d 100644 --- a/src/Data/Monoid.purs +++ b/src/Data/Monoid.purs @@ -28,6 +28,19 @@ import Type.Data.RowList (RLProxy(..)) -- | `Monoid`s are commonly used as the result of fold operations, where -- | `<>` is used to combine individual results, and `mempty` gives the result -- | of folding an empty collection of elements. +-- | +-- | ### Newtypes for Monoid +-- | +-- | Some types (e.g. `Int`, `Boolean`) can implement multiple law-abiding +-- | instances for `Monoid`. Let's use `Int` as an example +-- | 1. `<>` could be `+` and `mempty` could be `0` +-- | 2. `<>` could be `*` and `mempty` could be `1`. +-- | +-- | To clarify these ambiguous situations, one should use the newtypes +-- | defined in `Data.Monoid.` modules. +-- | +-- | In the above ambiguous situation, we could use `Additive` +-- | for the first situation or `Multiplicative` for the second one. class Semigroup m <= Monoid m where mempty :: m diff --git a/src/Data/Semigroup.purs b/src/Data/Semigroup.purs index db5bed20..aec1628b 100644 --- a/src/Data/Semigroup.purs +++ b/src/Data/Semigroup.purs @@ -18,7 +18,16 @@ import Type.Data.RowList (RLProxy(..)) -- | - Associativity: `(x <> y) <> z = x <> (y <> z)` -- | -- | One example of a `Semigroup` is `String`, with `(<>)` defined as string --- | concatenation. +-- | concatenation. Another example is `List a`, with `(<>)` defined as +-- | list concatenation. +-- | +-- | ### Newtypes for Semigroup +-- | +-- | There are two other ways to implement an instance for this type class +-- | regardless of which type is used. These instances can be used by +-- | wrapping the values in one of the two newtypes below: +-- | 1. `First` - Use the first argument every time: `append first _ = first`. +-- | 2. `Last` - Use the last argument every time: `append _ last = last`. class Semigroup a where append :: a -> a -> a diff --git a/src/Data/Void.purs b/src/Data/Void.purs index dd3efe38..89e0e1c6 100644 --- a/src/Data/Void.purs +++ b/src/Data/Void.purs @@ -2,11 +2,23 @@ module Data.Void (Void, absurd) where import Data.Show (class Show) --- | An uninhabited data type. +-- | An uninhabited data type. In other words, one can never create +-- | a runtime value of type `Void` becaue no such value exists. -- | -- | `Void` is useful to eliminate the possibility of a value being created. -- | For example, a value of type `Either Void Boolean` can never have -- | a Left value created in PureScript. +-- | +-- | This should not be confused with the keyword `void` that commonly appears in +-- | C-family languages, such as Java: +-- | ``` +-- | public class Foo { +-- | void doSomething() { System.out.println("hello world!"); } +-- | } +-- | ``` +-- | +-- | In PureScript, one often uses `Unit` to achieve similar effects as +-- | the `void` of C-family languages above. newtype Void = Void Void instance showVoid :: Show Void where