Merge pull request #217 from JordanMartinez/addDocs

Expand on documentation

Author: hdgarrood

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

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,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.<NewtypeName>` 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
 

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