Changes per @garyb

Author: marick

src/Data/Lens/At.purs

@@ -16,24 +16,22 @@ 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.
+-- | Use an `At` lens if you want to add
+-- | new elements or delete old ones:
 -- | 
 -- | ```purescript 
--- | > optic = at "key"
--- | > view optic $ Map.singleton "key" "value"
--- | (Just "value")
+-- | whole = Map.singleton "key" "value"
+-- | optic = at "key"
+-- |
+-- | view optic whole == Just "value"
 -- | 
--- | > set optic (Just "NEW") $ Map.singleton "key" "value"
--- | (fromFoldable [(Tuple "key" "NEW")])
+-- | set optic (Just "NEW") whole == Map.singleton "key" "NEW"
 -- | 
--- | > set optic Nothing $ Map.singleton "key" "value"
--- | (fromFoldable [])
+-- | set optic Nothing whole == Map.empty
 -- | ```
+-- |
+-- | If you want neither of those things, but only to view or change
+-- | an existing element, see `Data.Lens.Index`. 
 
 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,22 +15,32 @@ 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.
--- | 
+-- | Use an `Index` optic on types where: 
+-- | 1. The focus element might not be present.
+-- | 2. You either cannot or do not want to add new elements or delete existing ones. 
+-- |
+-- | `Array` is a typical example:
+-- |
 -- | ```purescript 
--- |> optic = ix 1
--- |> preview optic [0, 1, 2]
--- |(Just 1)
+-- | preview (ix 1) [0, 1, 2] == Just 1
+-- |
+-- | set (ix 1) 8888 [0, 1, 2] == [0,8888,2]
+-- | ```
 -- |
--- |> set optic 8888 [0, 1, 2]
--- |[0,8888,2]
+-- | Note the use of `preview` rather `view`.
+-- | 
+-- | Another common use is a `Map` that you don't want to either grow or shrink:
 -- |
--- |-- Note that `Index` lenses work with many types:
--- |> over optic negate $ Map.singleton 1 8888
--- |(fromFoldable [(Tuple 1 -8888)])
+-- | ```purescript 
+-- | (set (ix 1) 8888 $ Map.singleton 1 2) == Map.singleton 1 8888
+-- | 
+-- | (set (ix 1) 8888 $ Map.empty) == Map.empty
 -- | ```
+-- |
+-- | Note the second line: an attempt to `set` a missing focus element
+-- | leaves the original whole unchanged.
+-- |
+-- | If you *do* want to add or delete elements, see `Data.Lens.At`. 
 
 class Index m a b | m -> a, m -> b where
   ix :: a -> Traversal' m b

src/Data/Lens/Types.purs

@@ -27,21 +27,53 @@ import Data.Profunctor.Choice (class Choice)
 import Data.Profunctor.Closed (class Closed)
 import Data.Profunctor.Strong (class Strong)
 
--- | Given a type whose "focus element" can always be retrieved,
--- | a lens provides a convenient way to view, get, and transform
+-- | Given a type whose "focus element" always exists,
+-- | a lens provides a convenient way to view, set, and transform
 -- | that element. 
 -- | 
--- | `_2` is a Tuple-specific `Lens` available from `Data.Lens`, so:
+-- | For example, `_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)
+-- | over _2 String.length $ Tuple "ignore" "four" == Tuple "ignore" 4
 -- | ```
+-- | Note the result has a different type than the original tuple.
+-- | That is, the four `Lens` type variables have been narrowed to:
+-- |
+-- | * `s` is `Tuple String String`
+-- | * `t` is `Tuple String Int`
+-- | * `a` is `String`
+-- | * `b` is `Int`
+-- | 
+-- | See `Data.Lens.Getter` and `Data.Lens.Setter` for functions and operators
+-- | frequently used with lenses.
+
+
 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.
+-- | `Lens'` is a specialization of `Lens`. An optic of type `Lens'`
+-- | can change only the value of its focus,
+-- | not its type. As an example, consider the `Lens` `_2`, which has this type:
+-- |
+-- | ```purescript
+-- | _2 :: forall s t a b. Lens (Tuple s a) (Tuple t b) a b 
+-- | ```
+-- |
+-- | `_2` can produce a `Tuple Int String` from a `Tuple Int Int`:
+-- |
+-- | ```purescript
+-- | set _2 "NEW" (Tuple 1 2) == (Tuple 1 "NEW")
+-- | ```
+-- |
+-- | If we specialize `_2`'s type with `Lens'`, the following will not
+-- | type check:
+-- |
+-- | ```purescript
+-- | set (_2 :: Lens' (Tuple Int Int) Int) "NEW" (Tuple 1 2)
+-- |            ^^^^^^^^^^^^^^^^^^^^^^^^^
+-- | ```
+-- |
+-- | See `Data.Lens.Getter` and `Data.Lens.Setter` for functions and operators
+-- | frequently used with lenses.
+
 type Lens' s a = Lens s s a a
 
 -- | A prism.