Expand on documentation

src/Control/Applicative.purs

@@ -29,6 +29,38 @@ import Data.Unit (Unit, unit)
 -- | - Composition: `pure (<<<) <*> f <*> g <*> h = f <*> (g <*> h)`
 -- | - Homomorphism: `(pure f) <*> (pure x) = pure (f x)`
 -- | - Interchange: `u <*> (pure y) = (pure (_ $ y)) <*> u`
+-- |
+-- | ### Ado Notation
+-- |
+-- | When using a type that has an instance for `Applicative`, one can use
+-- | "ado notation." In short, this code...
+-- | ```
+-- | foo =
+-- |   functionThatTakes4Args <$> boxedA
+-- |                          <*> boxedB
+-- |                          <*> boxedUnit
+-- |                          <*> boxedC
+-- |   where
+-- |   functionThatTakes4Args a b _ c =
+-- |     let x = a * a + b
+-- |     in x + c
+-- | ```
+-- |
+-- | ... can be converted into into "ado notation:"
+-- | ```
+-- | foo = ado
+-- |   a <- boxedA
+-- |   b <- boxedB
+-- |   boxedUnit
+-- |   c <- boxedC
+-- |   let x = a * a + b
+-- |   in x + c
+-- | ```
+-- |
+-- | Note: if one wants to use "ado notation" but redefine what the in-scope
+-- | definitions are for `map`, `apply`, and `pure` in a given context, one can
+-- | use "qualified ado notation." This is an intermediate/advanced language
+-- | feature not explained here.
 class Apply f <= Applicative f where
   pure :: forall a. a -> f a
 

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:
 -- |

src/Control/Monad.purs

@@ -28,9 +28,64 @@ import Data.Unit (Unit)
 -- | - Left Identity: `pure x >>= f = f x`
 -- | - Right Identity: `x >>= pure = x`
 -- | - Applicative Superclass: `apply = ap`
+-- |
+-- | ### Do Notation
+-- |
+-- | When using a type that has an instance for `Monad`, one can use
+-- | "do notation." In short, this code...
+-- | ```
+-- | foo =
+-- |   bind boxedA (\a ->
+-- |     let b = a + 4
+-- |     in bind boxedC (\c ->
+-- |          bind boxedUnit (\_ ->
+-- |            pure (a * b - c)
+-- |          )
+-- |     )
+-- |   )
+-- | ```
+-- |
+-- | ... can be converted into this code...
+-- | ```
+-- | foo =
+-- |   boxedA >>= (\a ->
+-- |     let b = a + 4
+-- |     in boxedC >>= (\c ->
+-- |          boxedUnit >>= (\_ ->
+-- |            pure (a * b - c)
+-- |          )
+-- |     )
+-- |   )
+-- | ```
+-- |
+-- | ...which can be converted once more into "do notation:"
+-- | ```
+-- | foo = do
+-- |   a <- boxedA
+-- |   let b = a + 4
+-- |   c <- boxedC
+-- |   boxedUnit
+-- |   pure (a * b - c)
+-- | ```
+-- |
+-- | Note: if one wants to use "do notation" but redefine what the in-scope
+-- | definitions are for `bind` and `pure` in a given context, one can use
+-- | "qualified do notation." This is an intermediate/advanced language feature
+-- | not explained here.
 class (Applicative m, Bind m) <= Monad m
 
 instance monadFn :: Monad ((->) r)
+
+-- | The `Array` monad's "do notation" works like a nested for loop:
+-- | ```
+-- | foo :: Array Int
+-- | foo = do
+-- |   eachElementInArray1 <- [0, 1]
+-- |   eachElementInArray2 <- [1, 2]
+-- |   pure (eachElementInArray1 + eachElementInArray2)
+-- |
+-- | foo == [(0 + 1), (0 + 2), (1 + 1), (1 + 2)] == [1, 2, 2, 3]
+-- | ```
 instance monadArray :: Monad Array
 
 -- | `liftM1` provides a default implementation of `(<$>)` for any

src/Data/Monoid.purs

@@ -28,6 +28,20 @@ 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`. For example, `<>` could be `+` and `mempty` could
+-- | be `0`. Likewise, `<>` could be `*` and `mempty` could be `1`.
+-- | To workaround these ambiguous situations, one should use newtypes
+-- | to specify which instance should be used:
+-- | - `Additive`: use `Semiring`'s `plus`/`+` and `zero` for `<>` and `mempty`.
+-- | - `Multiplicative`: use `Semiring`'s `mul`/`*` and `one` for `<>` and `mempty`.
+-- | - `Conj`: use `HeytingAlgebra`'s `conj`/`&&` and `tt` for `<>` and `mempty`.
+-- | - `Disj`: use `HeytingAlgebra`'s `disj`/`||` and `ff` for `<>` and `mempty`.
+-- | - `Endo`: use `Category`'s `compose`/`<<<` and `identity` for `<>` and `mempty`.
+-- | - `Dual`: use `Category`'s `composeFlipped`/`>>>` and `identity` for `<>` and `mempty`.
 class Semigroup m <= Monoid m where
   mempty :: m
 

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
 

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 word, `void,` that commonly appears in
+-- | C-deriving 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 lowercased `void` above.
 newtype Void = Void Void
 
 instance showVoid :: Show Void where