Doctest fixes, etc.

src/Control/Lens/Traversal.hs

@@ -1,4 +1,3 @@
-{-# options_ghc -ddump-simpl #-}
 {-# LANGUAGE CPP #-}
 {-# LANGUAGE BangPatterns #-}
 {-# LANGUAGE DeriveFunctor #-}
@@ -177,7 +176,7 @@ import Data.Tuple.Solo (Solo (..), getSolo)
 import GHC.Magic (inline)
 
 -- $setup
--- >>> :set -XNoOverloadedStrings -XFlexibleContexts
+-- >>> :set -XNoOverloadedStrings -XFlexibleContexts -XRankNTypes
 -- >>> import Data.Char (toUpper)
 -- >>> import Control.Applicative
 -- >>> import Control.Lens
@@ -1493,9 +1492,15 @@ sequenceByOf l pur app = reifyApplicative pur app (l ReflectedApplicative)
 -- over' :: 'Traversal' s t a b -> (a -> b) -> s -> t
 -- @
 --
--- >>> over traverse (\x -> if x > 1 then undefined else pure x) [1,2]
--- [Exc
--- >>> over' traverse (\x -> if x > 1 then undefined else pure x) [1,2]
+-- >>> over traverse (\x -> if x > 1 then undefined else x) [1,2 :: Int]
+-- *** Exception: Prelude.undefined
+-- ^
+-- CallStack (from HasCallStack):
+--   error, called at libraries/base/GHC/Err.hs:79:14 in base:GHC.Err
+--   undefined, called at <interactive>:8184:36 in interactive:Ghci22
+-- [1,
+
+-- >>> over' traverse (\x -> if x > 1 then undefined else x) [1,2 :: Int]
 -- Exc
 over' :: LensLike Solo s t a b -> (a -> b) -> s -> t
 over' l f = getSolo . l (\old -> Solo $! f old)
@@ -1505,21 +1510,22 @@ over' l f = getSolo . l (\old -> Solo $! f old)
 -- applying the function. Alternatively, an indexed version of `over'`.
 -- See also 'strictly'.
 --
--- >>> iover' :: IndexedLens s t a b -> (i -> a -> b) -> s -> t
+-- >>> iover' :: IndexedLens i s t a b -> (i -> a -> b) -> s -> t
 -- iover' ::
--- >>> iover' :: IndexedTraversal s t a b -> (i -> a -> b) -> s -> t
+-- >>> iover' :: IndexedTraversal i s t a b -> (i -> a -> b) -> s -> t
 -- iover' ::
 -- @
 iover' :: Over (Indexed i) Solo s t a b -> (i -> a -> b) -> s -> t
 iover' l f = getSolo . l (Indexed $ \i a -> Solo $! f i a)
 {-# INLINE iover' #-}
 
--- | Use an optic /strictly/. This will force the results of /all/ the targets
--- before producing a new value. Note that producing an optic using 'strictly'
--- will not necessarily produce one even nearly as efficient as what could be
--- written by hand, although it will do so in simple enough situations. Be
--- particularly careful when working over many targets in a functor other than
--- 'Identity' or @'Const' c@; things may go very well or very badly.
+-- | Use an optic /strictly/. @strictly l f s@ will force the results of /all/
+-- the targets of @l@ before producing a new value. It does not affect folds or
+-- getters. Note that producing an optic using 'strictly' will not necessarily
+-- produce one even nearly as efficient as what could be written by hand,
+-- although it will do so in simple enough situations. Be particularly careful
+-- when working over many targets in a functor other than the usual 'Identity'
+-- or @'Const' c@; things may go very well or rather badly.
 --
 -- @
 -- 'over'' l = 'Control.Lens.Setter.over' (strictly l)
@@ -1531,7 +1537,7 @@ iover' l f = getSolo . l (Indexed $ \i a -> Solo $! f i a)
 -- strictly :: 'IndexedTraversal' i s t a b -> 'IndexedTraversal' i s t a b
 -- @
 strictly :: (Functor f, Profunctor p, Profunctor q) => Optical p q (BoxT f) s t a b -> Optical p q f s t a b
-strictly l f = rmap (fmap getSolo .# runBoxT) $ l (rmap (\mb -> BoxT ((Solo $!) <$> mb)) f)
+strictly l f = rmap (fmap getSolo .# runBoxT) $ l (rmap (BoxT #. fmap (Solo $!)) f)
 {-# INLINE strictly #-}
 
 -- | A very simple applicative transformer that gives us more control over when
@@ -1543,6 +1549,8 @@ newtype BoxT f a = BoxT
   { runBoxT :: f (Solo a) }
   deriving (Functor, Foldable, Traversable)
 
+-- The Contravariant instance allows a `strictly`-modified
+-- traversal to be used as a `Getter` or `Fold` for convenience.
 instance Contravariant f => Contravariant (BoxT f) where
   contramap f (BoxT m) = BoxT $ contramap (fmap f) m
 instance Apply f => Apply (BoxT f) where