Expand on documentation

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/Bind.purs

@@ -63,6 +63,17 @@ infixr 1 bindFlipped as =<<
 instance bindFn :: Bind ((->) r) where
   bind m f x = f (m x) x
 
+-- | The `Array` monad works like a nested for loop. Each
+-- | `bind`/`>>=` adds another level of nesting in the loop:
+-- | ```
+-- | foo :: Array Int
+-- | foo = do
+-- |   ["a", "b"] >>= \eachElementInArray1 ->
+-- |     ["c", "d"] >>= \eachElementInArray2
+-- |       pure (eachElementInArray1 <> eachElementInArray2)
+-- |
+-- | foo == [ ("a" <> "c"), ("a" <> "d"), ("b" <> "c"), ("b" <> "d") == [ "ac", "ad", "bc", "bd"]
+-- | ```
 instance bindArray :: Bind Array where
   bind = arrayBind
 

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

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