Merge pull request #11 from born2defy/DocDumbDown

Function examples of Strong and Choice for approachability

Author: garyb

docs/Data/Profunctor.md

@@ -52,5 +52,3 @@ arr :: forall a b p. (Category p, Profunctor p) => (a -> b) -> p a b
 ```
 
 Lift a pure function into any `Profunctor` which is also a `Category`.
-
-

docs/Data/Profunctor/Choice.md

@@ -14,6 +14,21 @@ sum types.
 `left` and `right` lift values in a `Profunctor` to act on the `Left` and
 `Right` components of a sum, respectively.
 
+Looking at `Choice` through the intuition of inputs and outputs
+yields the following type signature:
+```
+left ::  forall input output a. p input output -> p (Either input a) (Either output a)
+right :: forall input output a. p input output -> p (Either a input) (Either a output)
+```
+If we specialize the profunctor `p` to the `function` arrow, we get the following type
+signatures:
+```
+left ::  forall input output a. (input -> output) -> (Either input a) -> (Either output a)
+right :: forall input output a. (input -> output) -> (Either a input) -> (Either a output)
+```
+When the `profunctor` is `Function` application, `left` allows you to map a function over the
+left side of an `Either`, and `right` maps it over the right side (same as `map` would do).
+
 ##### Instances
 ``` purescript
 instance choiceFn :: Choice Function
@@ -30,6 +45,14 @@ _right-associative / precedence 2_
 Compose a value acting on a sum from two values, each acting on one of
 the components of the sum.
 
+Specializing `(+++)` to function application would look like this:
+```
+(+++) :: forall a b c d. (a -> b) -> (c -> d) -> (Either a c) -> (Either b d)
+```
+We take two functions, `f` and `g`, and we transform them into a single function which
+takes an `Either`and maps `f` over the left side and `g` over the right side.  Just like
+`bi-map` would do for the `bi-functor` instance of `Either`.
+
 #### `(|||)`
 
 ``` purescript
@@ -44,4 +67,13 @@ one side of the sum.
 This combinator is useful when assembling values from smaller components,
 because it provides a way to support two different types of input.
 
-
+Specializing `(|||)` to function application would look like this:
+```
+(|||) :: forall a b c d. (a -> c) -> (b -> c) -> Either a b -> c
+```
+We take two functions, `f` and `g`, which both return the same type `c` and we transform them into a
+single function which takes an `Either` value with the parameter type of `f` on the left side and
+the parameter type of `g` on the right side. The function then runs either `f` or `g`, depending on
+whether the `Either` value is a `Left` or a `Right`.
+This allows us to bundle two different computations which both have the same result type into one
+function which will run the approriate computation based on the parameter supplied in the `Either` value.

docs/Data/Profunctor/Star.md

@@ -23,5 +23,3 @@ runStar :: forall f a b. Star f a b -> a -> f b
 ```
 
 Unwrap a value of type `Star f a b`.
-
-

docs/Data/Profunctor/Strong.md

@@ -14,6 +14,21 @@ product types.
 `first` and `second` lift values in a `Profunctor` to act on the first and
 second components of a `Tuple`, respectively.
 
+Another way to think about Strong is to piggyback on the intuition of
+inputs and outputs.  Rewriting the type signature in this light then yields:
+```
+first ::  forall input output a. p input output -> p (Tuple input a) (Tuple output a)
+second :: forall input output a. p input output -> p (Tuple a input) (Tuple a output)
+```
+If we specialize the profunctor p to the function arrow, we get the following type
+signatures, which may look a bit more familiar:
+```
+first ::  forall input output a. (input -> output) -> (Tuple input a) -> (Tuple output a)
+second :: forall input output a. (input -> output) -> (Tuple a input) -> (Tuple a output)
+```
+So, when the `profunctor` is `Function` application, `first` essentially applies your function
+to the first element of a `Tuple`, and `second` applies it to the second element (same as `map` would do).
+
 ##### Instances
 ``` purescript
 instance strongFn :: Strong Function
@@ -30,6 +45,14 @@ _right-associative / precedence 3_
 Compose a value acting on a `Tuple` from two values, each acting on one of
 the components of the `Tuple`.
 
+Specializing `(***)` to function application would look like this:
+```
+(***) :: forall a b c d. (a -> b) -> (c -> d) -> (Tuple a c) -> (Tuple b d)
+```
+We take two functions, `f` and `g`, and we transform them into a single function which
+takes a `Tuple` and maps `f` over the first element and `g` over the second.  Just like `bi-map`
+would do for the `bi-functor` instance of `Tuple`.
+
 #### `(&&&)`
 
 ``` purescript
@@ -44,4 +67,11 @@ one side of the `Tuple`.
 This combinator is useful when assembling values from smaller components,
 because it provides a way to support two different types of output.
 
-
+Specializing `(&&&)` to function application would look like this:
+```
+(&&&) :: forall a b c d. (a -> b) -> (a -> c) -> (a -> (Tuple b c))
+```
+We take two functions, `f` and `g`, with the same parameter type and we transform them into a
+single function which takes one parameter and returns a `Tuple` of the results of running
+`f` and `g` on the parameter, respectively.  This allows us to run two parallel computations
+on the same input and return both results in a `Tuple`.

src/Data/Profunctor/Choice.purs

@@ -10,6 +10,21 @@ import Data.Profunctor
 -- |
 -- | `left` and `right` lift values in a `Profunctor` to act on the `Left` and
 -- | `Right` components of a sum, respectively.
+-- |
+-- | Looking at `Choice` through the intuition of inputs and outputs
+-- | yields the following type signature:
+-- | ```
+-- | left ::  forall input output a. p input output -> p (Either input a) (Either output a)
+-- | right :: forall input output a. p input output -> p (Either a input) (Either a output)
+-- | ```
+-- | If we specialize the profunctor `p` to the `function` arrow, we get the following type
+-- | signatures:
+-- | ```
+-- | left ::  forall input output a. (input -> output) -> (Either input a) -> (Either output a)
+-- | right :: forall input output a. (input -> output) -> (Either a input) -> (Either a output)
+-- | ```
+-- | When the `profunctor` is `Function` application, `left` allows you to map a function over the
+-- | left side of an `Either`, and `right` maps it over the right side (same as `map` would do).
 class (Profunctor p) <= Choice p where
   left :: forall a b c. p a b -> p (Either a c) (Either b c)
   right :: forall a b c. p b c -> p (Either a b) (Either a c)
@@ -24,6 +39,14 @@ infixr 2 |||
 
 -- | Compose a value acting on a sum from two values, each acting on one of
 -- | the components of the sum.
+-- |
+-- | Specializing `(+++)` to function application would look like this:
+-- | ```
+-- | (+++) :: forall a b c d. (a -> b) -> (c -> d) -> (Either a c) -> (Either b d)
+-- | ```
+-- | We take two functions, `f` and `g`, and we transform them into a single function which
+-- | takes an `Either`and maps `f` over the left side and `g` over the right side.  Just like
+-- | `bi-map` would do for the `bi-functor` instance of `Either`.
 (+++) :: forall p a b c d. (Category p, Choice p) => p a b -> p c d -> p (Either a c) (Either b d)
 (+++) l r = left l >>> right r
 
@@ -32,6 +55,17 @@ infixr 2 |||
 -- |
 -- | This combinator is useful when assembling values from smaller components,
 -- | because it provides a way to support two different types of input.
+-- |
+-- | Specializing `(|||)` to function application would look like this:
+-- | ```
+-- | (|||) :: forall a b c d. (a -> c) -> (b -> c) -> Either a b -> c
+-- | ```
+-- | We take two functions, `f` and `g`, which both return the same type `c` and we transform them into a
+-- | single function which takes an `Either` value with the parameter type of `f` on the left side and
+-- | the parameter type of `g` on the right side. The function then runs either `f` or `g`, depending on
+-- | whether the `Either` value is a `Left` or a `Right`.
+-- | This allows us to bundle two different computations which both have the same result type into one
+-- | function which will run the approriate computation based on the parameter supplied in the `Either` value.
 (|||) :: forall p a b c. (Category p, Choice p) => p a c -> p b c -> p (Either a b) c
 (|||) l r = (l +++ r) >>> join
   where

src/Data/Profunctor/Strong.purs

@@ -10,6 +10,21 @@ import Data.Tuple (Tuple(..))
 -- |
 -- | `first` and `second` lift values in a `Profunctor` to act on the first and
 -- | second components of a `Tuple`, respectively.
+-- |
+-- | Another way to think about Strong is to piggyback on the intuition of
+-- | inputs and outputs.  Rewriting the type signature in this light then yields:
+-- | ```
+-- | first ::  forall input output a. p input output -> p (Tuple input a) (Tuple output a)
+-- | second :: forall input output a. p input output -> p (Tuple a input) (Tuple a output)
+-- | ```
+-- | If we specialize the profunctor p to the function arrow, we get the following type
+-- | signatures, which may look a bit more familiar:
+-- | ```
+-- | first ::  forall input output a. (input -> output) -> (Tuple input a) -> (Tuple output a)
+-- | second :: forall input output a. (input -> output) -> (Tuple a input) -> (Tuple a output)
+-- | ```
+-- | So, when the `profunctor` is `Function` application, `first` essentially applies your function
+-- | to the first element of a `Tuple`, and `second` applies it to the second element (same as `map` would do).
 class (Profunctor p) <= Strong p where
   first :: forall a b c. p a b -> p (Tuple a c) (Tuple b c)
   second :: forall a b c. p b c -> p (Tuple a b) (Tuple a c)
@@ -23,6 +38,14 @@ infixr 3 &&&
 
 -- | Compose a value acting on a `Tuple` from two values, each acting on one of
 -- | the components of the `Tuple`.
+-- |
+-- | Specializing `(***)` to function application would look like this:
+-- | ```
+-- | (***) :: forall a b c d. (a -> b) -> (c -> d) -> (Tuple a c) -> (Tuple b d)
+-- | ```
+-- | We take two functions, `f` and `g`, and we transform them into a single function which
+-- | takes a `Tuple` and maps `f` over the first element and `g` over the second.  Just like `bi-map`
+-- | would do for the `bi-functor` instance of `Tuple`.
 (***) :: forall p a b c d. (Category p, Strong p) => p a b -> p c d -> p (Tuple a c) (Tuple b d)
 (***) l r = first l >>> second r
 
@@ -31,6 +54,15 @@ infixr 3 &&&
 -- |
 -- | This combinator is useful when assembling values from smaller components,
 -- | because it provides a way to support two different types of output.
+-- |
+-- | Specializing `(&&&)` to function application would look like this:
+-- | ```
+-- | (&&&) :: forall a b c d. (a -> b) -> (a -> c) -> (a -> (Tuple b c))
+-- | ```
+-- | We take two functions, `f` and `g`, with the same parameter type and we transform them into a
+-- | single function which takes one parameter and returns a `Tuple` of the results of running
+-- | `f` and `g` on the parameter, respectively.  This allows us to run two parallel computations
+-- | on the same input and return both results in a `Tuple`.
 (&&&) :: forall p a b c. (Category p, Strong p) => p a b -> p a c -> p a (Tuple b c)
 (&&&) l r = split >>> (l *** r)
   where