Added commentary

Author: marick

src/Data/Lens/At.purs

@@ -3,6 +3,7 @@ module Data.Lens.At
   , at
   ) where
 
+
 import Prelude
 
 import Data.Identity (Identity(..))
@@ -15,6 +16,25 @@ import Data.Newtype (unwrap)
 import Data.Lens (Lens', lens)
 import Data.Lens.Index (class Index)
 
+
+-- | `At` is useful for types like `Data.Map`:
+-- | 
+-- | * The result of getting an element is a `Maybe a`. 
+-- | * New elements can be added.
+-- | * Existing elements can be deleted.
+-- | 
+-- | ```purescript 
+-- | > optic = at "key"
+-- | > view optic $ Map.singleton "key" "value"
+-- | (Just "value")
+-- | 
+-- | > set optic (Just "NEW") $ Map.singleton "key" "value"
+-- | (fromFoldable [(Tuple "key" "NEW")])
+-- | 
+-- | > set optic Nothing $ Map.singleton "key" "value"
+-- | (fromFoldable [])
+-- | ```
+
 class Index m a b <= At m a b | m -> a, m -> b where
   at :: a -> Lens' m (Maybe b)
 

src/Data/Lens/Index.purs

@@ -15,6 +15,23 @@ import Data.Set as S
 import Data.StrMap as SM
 import Data.Traversable (traverse)
 
+-- | `Index` is useful when a focus element might not be present.
+-- | It allows you to `set` an existing focus element, but you cannot add a
+-- | new one or delete an old one.
+-- | 
+-- | ```purescript 
+-- |> optic = ix 1
+-- |> preview optic [0, 1, 2]
+-- |(Just 1)
+-- |
+-- |> set optic 8888 [0, 1, 2]
+-- |[0,8888,2]
+-- |
+-- |-- Note that `Index` lenses work with many types:
+-- |> over optic negate $ Map.singleton 1 8888
+-- |(fromFoldable [(Tuple 1 -8888)])
+-- | ```
+
 class Index m a b | m -> a, m -> b where
   ix :: a -> Traversal' m b
 

src/Data/Lens/Lens.purs

@@ -24,13 +24,24 @@ import Data.Profunctor.Strong (first)
 import Data.Tuple (Tuple(..))
 import Data.Newtype(un)
 
-lens' :: forall s t a b. (s -> Tuple a (b -> t)) -> Lens s t a b
-lens' to pab = dimap to (\(Tuple b f) -> f b) (first pab)
-
 -- | Create a `Lens` from a getter/setter pair.
+-- |
+-- | ```purescript
+-- | > species = lens _.species $ _ {species = _}
+-- | > view species {species : "bovine"}
+-- | "bovine"
+-- |
+-- | > _2 = lens Tuple.snd $ \(Tuple keep _) new -> Tuple keep new
+-- | ```
+-- |
+-- | Note: `_2` is predefined in `Data.Lens.Tuple`.
+
 lens :: forall s t a b. (s -> a) -> (s -> b -> t) -> Lens s t a b
 lens get set = lens' \s -> Tuple (get s) \b -> set s b
 
+lens' :: forall s t a b. (s -> Tuple a (b -> t)) -> Lens s t a b
+lens' to pab = dimap to (\(Tuple b f) -> f b) (first pab)
+
 withLens :: forall s t a b r. ALens s t a b -> ((s -> a) -> (s -> b -> t) -> r) -> r
 withLens l f = case l (Shop id \_ b -> b) of Shop x y -> f x y
 

src/Data/Lens/Types.purs

@@ -27,21 +27,45 @@ import Data.Profunctor.Choice (class Choice)
 import Data.Profunctor.Closed (class Closed)
 import Data.Profunctor.Strong (class Strong)
 
--- | A general-purpose Data.Lens.
-type Optic p s t a b = p a b -> p s t
-type Optic' p s a = Optic p s s a a
+-- | Given a type whose "focus element" can always be retrieved,
+-- | a lens provides a convenient way to view, get, and transform
+-- | that element. 
+-- | 
+-- | `_2` is a Tuple-specific `Lens` available from `Data.Lens`, so:
+-- | ```purescript
+-- | > import Data.Lens
+-- | > over _2 String.length $ Tuple "ignore" "four"
+-- | (Tuple "ignore" 4)
+-- | ```
+type Lens s t a b = forall p. Strong p => Optic p s t a b
+
+-- | `Lens` allows `set` to change the type of the focus. Often, a
+-- | particular lens won't do that. This type alias declares that `set`
+-- | only changes values, not types.
+type Lens' s a = Lens s s a a
+
+-- | A prism.
+type Prism s t a b = forall p. Choice p => Optic p s t a b
+type Prism' s a = Prism s s a a
 
 -- | A generalized isomorphism.
 type Iso s t a b = forall p. Profunctor p => Optic p s t a b
 type Iso' s a = Iso s s a a
 
+-- | A traversal.
+type Traversal s t a b = forall p. Wander p => Optic p s t a b
+type Traversal' s a = Traversal s s a a
+
+
+
+
+-- | A general-purpose Data.Lens.
+type Optic p s t a b = p a b -> p s t
+type Optic' p s a = Optic p s s a a
+
 type AnIso s t a b = Optic (Exchange a b) s t a b
 type AnIso' s a = AnIso s s a a
 
--- | A lens.
-type Lens s t a b = forall p. Strong p => Optic p s t a b
-type Lens' s a = Lens s s a a
-
 type ALens s t a b = Optic (Shop a b) s t a b
 type ALens' s a = ALens s s a a
 
@@ -52,17 +76,9 @@ type IndexedLens' i s a = IndexedLens i s s a a
 type AnIndexedLens i s t a b = IndexedOptic (Shop (Tuple i a) b) i s t a b
 type AnIndexedLens' i s a = AnIndexedLens i s s a a
 
--- | A prism.
-type Prism s t a b = forall p. Choice p => Optic p s t a b
-type Prism' s a = Prism s s a a
-
 type APrism s t a b = Optic (Market a b) s t a b
 type APrism' s a = APrism s s a a
 
--- | A traversal.
-type Traversal s t a b = forall p. Wander p => Optic p s t a b
-type Traversal' s a = Traversal s s a a
-
 -- | A grate (http://r6research.livejournal.com/28050.html)
 type Grate s t a b = forall p. Closed p => Optic p s t a b
 type Grate' s a = Grate s s a a