Split “why this format” into a README.md

Author: marick

examples/README.md

@@ -0,0 +1,45 @@
+## Examples
+
+* [Using Prisms with Sum Types](src/PrismsForSumTypes.purs)
+
+## Conventions and the "why" behind them
+
+The examples are meant to be read from top to bottom.
+
+Every example is self-contained and can be imported into the repl. The
+top of an example module will have a comment like this:
+
+```purescript
+{-   If you want to try out examples, paste the following into the repl.
+
+import PrismsForSumTypes
+import Data.Lens
+
+-}
+```
+
+The modules contain both definitions of optics and sample uses. The
+sample uses are executable code that look like this:
+
+```purescript
+s1 :: Maybe Color
+s1 = preview solidFocus (Solid Color.white) -- (Just rgba 255 255 255 1.0)
+```
+
+Why?
+
+1. The second line can be pasted into the repl without needing to use
+   `:paste`. (I usually don't copy the `s1 =` because I prefer seeing
+   the results immediately. All types in the examples implement `show`,
+   making that painless.)
+   
+2. The sample uses are executable code so that the compiler checks
+   them and -- more importantly -- so that they stand out from the
+   surrounding commentary. That makes an example more easily scannable
+   when you're refreshing your memory about a particular usage
+   (assuming you use a syntax highlighter).
+
+3. The name-value bindings (like `s1`) are clutter, but required by the
+   compiler. Most of the type annotations are also clutter, but are required
+   to prevent compiler warnings in, for example, `pulp build`.
+

examples/src/PrismsForSumTypes.purs

@@ -9,15 +9,7 @@ import Color as Color
 import Data.Maybe
 import Data.Record.ShowRecord (showRecord)
 
-Examples are written in this format:
-
-s1 :: Maybe Color
-s1 = preview solidFocus (Solid Color.white) -- (Just rgba 255 255 255 1.0)
-
-That's so that a typical syntax highlighter will make the executable
-code easy to spot among the commentary. (The name-value bindings and
-type annotations are unfortunate clutter, but needed to prevent noise
-from compiler warnings.)
+See `README.md` if you're wondering why code is formatted the way it is.
 
 -}
 
@@ -80,11 +72,11 @@ instance showFill :: Show Fill where
 
 
                 {------ Making prisms with Maybe and `prism'` ------}
-                {------ Basic usage ------}
+                {------ Basic usage: `preview`, `review`, `is`, and `isn't` ------}
 
 -- Two function arguments: a data constructor for the type in
--- question, plus one that "substitutes" your desired case with `Just`
--- and converts all other values to `Nothing`.
+-- question, plus one that converts your desired case to a
+-- `Just <wrapped values>` or `Nothing`.
 
 solidFocus :: Prism' Fill Color
 solidFocus = prism' constructor focus