Skip to content
Browse files

haddocks: post-"Internalization" clean-up, round 4

  • Loading branch information...
1 parent 7a1c95e commit 105b1b42f33071158a6d1cb75fab975ab1956dd1 @basdirks basdirks committed Jan 14, 2013
View
10 src/Control/Lens/Indexed.hs
@@ -116,7 +116,7 @@ infixr 9 <.>, <., .>
--
-- Mnemonically, the @>@ points to the indexing we want to preserve.
--
--- This is the same as @('.')@: @f '.' g@ gives you @g@'s index.
+-- This is the same as @('.')@. @f '.' g@ gives you the index of @g@.
(.>) :: (st -> r) -> (kab -> st) -> kab -> r
(.>) = (.)
{-# INLINE (.>) #-}
@@ -129,7 +129,7 @@ reindexed :: Indexable j p => (i -> j) -> (Indexed i a b -> r) -> p a b -> r
reindexed ij f g = f . Indexed $ indexed g . ij
{-# INLINE reindexed #-}
--- | Composition of 'Indexed' functions
+-- | Composition of 'Indexed' functions.
--
-- Mnemonically, the @\<@ and @\>@ points to the fact that we want to preserve the indices.
(<.>) :: Indexable (i, j) p => (Indexed i s t -> r) -> (Indexed j a b -> s -> t) -> p a b -> r
@@ -193,7 +193,7 @@ index j f = Indexed $ \i a -> if j == i then indexed f i a else pure a
-- Instances must satisfy a modified form of the 'Functor' laws:
--
-- @
--- 'imap' f '.' 'imap' g ≡ 'imap' (\\i -> f i . g i)
+-- 'imap' f '.' 'imap' g ≡ 'imap' (\\i -> f i '.' g i)
-- 'imap' (\\_ a -> a) ≡ 'id'
-- @
class Functor f => FunctorWithIndex i f | f -> i where
@@ -398,7 +398,7 @@ itoList = ifoldr (\i c -> ((i,c):)) []
--
-- @
-- 'itraverse' ('const' 'Identity') ≡ 'Identity'
--- 'fmap' ('itraverse' f) '.' 'itraverse' g ≡ 'getCompose' '.' 'itraverse' (\\i -> 'Compose' '.' 'fmap' (f i) '.' g i)
+-- 'fmap' ('itraverse' f) '.' 'itraverse' g ≡ 'Data.Functor.Compose.getCompose' '.' 'itraverse' (\\i -> 'Data.Functor.Compose.Compose' '.' 'fmap' (f i) '.' g i)
-- @
class (FunctorWithIndex i t, FoldableWithIndex i t, Traversable t) => TraversableWithIndex i t | t -> i where
-- | Traverse an indexed container.
@@ -414,7 +414,7 @@ itraversed :: TraversableWithIndex i f => IndexedTraversal i (f a) (f b) a b
itraversed = itraverse . indexed
{-# INLINE itraversed #-}
--- | Traverse with an index (and the arguments flipped)
+-- | Traverse with an index (and the arguments flipped).
--
-- @
-- 'for' a ≡ 'ifor' a '.' 'const'
View
2 src/Control/Lens/Internal/Bazaar.hs
@@ -58,7 +58,7 @@ class Profunctor p => Bizarre p w | w -> p where
--
-- Where a @'Context' a b t@ holds an @a@ and a function from @b@ to
-- @t@, a @'Bazaar' a b t@ holds @N@ @a@s and a function from @N@
--- @b@s to @t@, (where @N@ might be infinite)
+-- @b@s to @t@, (where @N@ might be infinite).
--
-- Mnemonically, a 'Bazaar' holds many stores and you can easily add more.
--
View
2 src/Control/Lens/Internal/Fold.hs
@@ -104,7 +104,7 @@ instance Ord a => Monoid (Max a) where
mappend (Max a) (Max b) = Max (max a b)
{-# INLINE mappend #-}
--- | Obtain the maximum
+-- | Obtain the maximum.
getMax :: Max a -> Maybe a
getMax NoMax = Nothing
getMax (Max a) = Just a
View
10 src/Control/Lens/Internal/Indexed.hs
@@ -198,8 +198,8 @@ instance i ~ j => Indexable i (Indexed j) where
-- Indexing
------------------------------------------------------------------------------
--- | Applicative composition of @'Control.Monad.Trans.State.Lazy.State' 'Int'@ with a 'Functor', used
--- by 'Control.Lens.Indexed.indexed'
+-- | 'Applicative' composition of @'Control.Monad.Trans.State.Lazy.State' 'Int'@ with a 'Functor', used
+-- by 'Control.Lens.Indexed.indexed'.
newtype Indexing f a = Indexing { runIndexing :: Int -> (Int, f a) }
instance Functor f => Functor (Indexing f) where
@@ -242,8 +242,8 @@ indexing l iafb s = snd $ runIndexing (l (\a -> Indexing (\i -> i `seq` (i + 1,
------------------------------------------------------------------------------
--- | Applicative composition of @'Control.Monad.Trans.State.Lazy.State' 'Int64'@ with a 'Functor', used
--- by 'Control.Lens.Indexed.indexed64'
+-- | 'Applicative' composition of @'Control.Monad.Trans.State.Lazy.State' 'Int64'@ with a 'Functor', used
+-- by 'Control.Lens.Indexed.indexed64'.
newtype Indexing64 f a = Indexing64 { runIndexing64 :: Int64 -> (Int64, f a) }
instance Functor f => Functor (Indexing64 f) where
@@ -267,7 +267,7 @@ instance Gettable f => Gettable (Indexing64 f) where
-- | Transform a 'Control.Lens.Traversal.Traversal' into an 'Control.Lens.Traversal.IndexedTraversal' or
-- a 'Control.Lens.Fold.Fold' into an 'Control.Lens.Fold.IndexedFold', etc.
--
--- This combinator is like 'indexing' except that it handles large 'Control.Lens.Traversal.Traversal's and 'Control.Lens.Fold.Fold's gracefully.
+-- This combinator is like 'indexing' except that it handles large traversals and folds gracefully.
--
-- @
-- 'indexing64' :: 'Control.Lens.Type.Traversal' s t a b -> 'Control.Lens.Type.IndexedTraversal' 'Int64' s t a b
View
2 src/Control/Lens/Internal/Instances.hs
@@ -8,7 +8,7 @@
-- Stability : experimental
-- Portability : non-portable
--
--- This module includes orphan instances for (,), 'Either' and 'Const' that
+-- This module includes orphan instances for @(,)@, 'Either' and 'Const' that
-- should be supplied by base.
----------------------------------------------------------------------------
module Control.Lens.Internal.Instances () where
View
25 src/Control/Lens/Internal/Jacket.hs
@@ -25,7 +25,7 @@
--
-- This module provides internal types and functions used in the implementation
-- of @Control.Lens.Zipper@. You shouldn't need to import it directly, and the
--- exported types can be used to break 'Zipper' invariants.
+-- exported types can be used to break 'Control.Lens.Zipper.Zipper' invariants.
--
----------------------------------------------------------------------------
module Control.Lens.Internal.Jacket
@@ -207,7 +207,7 @@ ijacket l = iso (tailored `rmap` l (Indexed $ \i a -> Tailor 1 $ \o -> JacketLea
------------------------------------------------------------------------------
#ifndef HLINT
--- | A Path into a 'Jacket' that ends at a 'JacketLeaf'
+-- | A 'Path' into a 'Jacket' that ends at a 'JacketLeaf'.
data Path :: * -> * -> * -> * -> * -> * where
ApL :: Int -> Int -> !(Path i t y b a) -> !(Jacket i x b a) -> Path i t (x -> y) b a
ApR :: Int -> Int -> !(Jacket i (x -> y) b a) -> !(Path i t y b a) -> Path i t x b a
@@ -241,11 +241,12 @@ instance FunctorWithIndex i (Path i t y b) where
-- "list case", where the traversal tree is right-biased, as in (Ap (Leaf (Identity x))
-- (Ap (Leaf (Identity y)) ...)). It should be safe to delete any of these cases.
--- | Reconstruct a 'Jacket' from a 'Path' to a leaf and a new value for the leaf.
--- recompress :: Path i z t b a -> Int -> i -> a -> Jacket i z b a
+-- | Reconstruct a 'Jacket' from a 'Path' to a 'JacketLeaf' and a new value for the 'JacketLeaf'.
+
+-- @'recompress' :: 'Path' i z t b a -> 'Int' -> i -> a -> 'Jacket' i z b a@
recompress :: Path i t b b a -> Int -> i -> a -> Jacket i t b a
-recompress Start o i a = JacketLeaf o i a -- Unrolled: The lens case.
+recompress Start o i a = JacketLeaf o i a -- Unrolled: The 'Lens' case.
recompress (ApL s oa Start r) o i a = JacketAp s oa (Left i) (Left ((id ||| const i) $ jackr r)) (JacketLeaf o i a) r -- Unrolled: The list case. In particular, a right-biased tree that we haven't moved rightward in.
recompress p o0 i a = go p (JacketLeaf o0 i a) where
go :: Path i t x b a -> Jacket i x b a -> Jacket i t b a
@@ -254,7 +255,7 @@ recompress p o0 i a = go p (JacketLeaf o0 i a) where
go (ApR s oa l q) r = go q (jack s oa l r)
{-# INLINE recompress #-}
--- reassemble a jacket. Note: upon reassembly, both 'jackl' and 'jackr' will both be 'Right', so we could improve this a lot
+-- reassemble a 'Jacket'. Note: upon reassembly, both 'jackl' and 'jackr' will both be 'Right', so we could improve this a lot.
jack :: Int -> Int -> Jacket i (x -> y) b a -> Jacket i x b a -> Jacket i y b a
jack s o l r = JacketAp s o (Right (fromRight (jackl l <*> jackl r))) (Right (fromRight ((&) <$> jackr r <*> jackr l))) l r
{-# INLINE jack #-}
@@ -265,12 +266,12 @@ fromRight (Right b) = b
{-# INLINE fromRight #-}
startl :: forall a b i r x y. Path i y x b a -> Jacket i x b a -> r -> (Path i y b b a -> Int -> i -> a -> r) -> r
-startl p0 (JacketLeaf o i a) _ kp = kp p0 o i a -- Unrolled: The lens case.
+startl p0 (JacketLeaf o i a) _ kp = kp p0 o i a -- Unrolled: The 'Lens' case.
startl p0 (JacketAp s oa _ _ (JacketLeaf o i a) r) _ kp = kp (ApL s oa p0 r) o i a -- Unrolled: The list case. (Is this one a good idea?)
startl p0 c0 kn kp = go p0 c0 where
go :: Path i y x' b a -> Jacket i x' b a -> r
go p (JacketAp s oa _ _ l r) = case jackl l of
- Right xy -> go (ApR s oa (JacketPure xy) p) r -- skip the empty side, and record it as pure
+ Right xy -> go (ApR s oa (JacketPure xy) p) r -- skip the empty side, and record it as pure.
Left _ -> go (ApL s oa p r) l
go p (JacketLeaf o i a) = kp p o i a
go _ (JacketPure _) = kn
@@ -287,18 +288,18 @@ startr p0 c0 kn kp = go p0 c0 where
go _ (JacketPure _) = kn
{-# INLINE startr #-}
--- | Move left one leaf
+-- | Move left one 'JacketLeaf'.
movel :: forall a b i r x y. Path i y x b a -> Jacket i x b a -> r -> (Path i y b b a -> Int -> i -> a -> r) -> r
movel p0 c0 kn kp = go p0 c0 where
go :: Path i y x' b a -> Jacket i x' b a -> r
go Start _ = kn
go (ApR s oa l q) r = case jackr l of
- Right xy -> go q (jack s oa (JacketPure xy) r) -- l is pure
- Left _ -> startr (ApL s oa q r) l kn kp -- l has a rightmost element, descend into it
+ Right xy -> go q (jack s oa (JacketPure xy) r) -- l is pure.
+ Left _ -> startr (ApL s oa q r) l kn kp -- l has a rightmost element, descend into it.
go (ApL s oa p r) l = go p (jack s oa l r)
{-# INLINE movel #-}
--- | Move right one leaf
+-- | Move right one 'JacketLeaf'.
mover :: forall a b i r x y. Path i y x b a -> Jacket i x b a -> r -> (Path i y b b a -> Int -> i -> a -> r) -> r
mover p0 c0 kn kp = go p0 c0 where
go :: Path i y x' b a -> Jacket i x' b a -> r
View
2 src/Control/Lens/Internal/Review.hs
@@ -47,7 +47,7 @@ import Unsafe.Coerce
-- Reviewable
----------------------------------------------------------------------------
--- | This provides a dual notion to that of 'Gettable'.
+-- | This provides a dual notion to that of 'Control.Lens.Getter.Gettable'.
class Profunctor p => Reviewable p where
retagged :: p a b -> p s b
-- retaggedDot, dotRetagged?
View
2 src/Control/Lens/Internal/Scoria.hs
@@ -84,7 +84,7 @@ instance (Show i, Show a) => Show (Scoria i t b a) where
-- Molten
------------------------------------------------------------------------------
--- | A non-reassociating initially encoded version of 'Bazaar'
+-- | A non-reassociating initially encoded version of 'Bazaar'.
newtype Molten i a b t = Molten { runMolten :: Scoria i t b a }
instance Functor (Molten i a b) where
View
4 src/Control/Lens/Internal/Setter.hs
@@ -46,7 +46,7 @@ class (Applicative f, Distributive f, Traversable f) => Settable f where
taintedDot g = g `seq` rmap pure g
{-# INLINE taintedDot #-}
--- | so you can pass our a 'Control.Lens.Setter.Setter' into combinators from other 'Lens' libraries
+-- | So you can pass our 'Control.Lens.Setter.Setter' into combinators from other lens libraries.
instance Settable Identity where
untainted = runIdentity
{-# INLINE untainted #-}
@@ -69,7 +69,7 @@ instance (Settable f, Settable g) => Settable (Compose f g) where
-----------------------------------------------------------------------------
-- | 'Mutator' is just a renamed 'Identity' 'Functor' to give better error
--- messages when someone attempts to use a 'Getter' as a 'Setter'.
+-- messages when someone attempts to use a 'Control.Lens.Getter.Getter' as a 'Control.Lens.Setter.Setter'.
--
-- Most user code will never need to see this type.
newtype Mutator a = Mutator { runMutator :: a }
View
6 src/Control/Lens/Internal/Zip.hs
@@ -145,7 +145,7 @@ instance Comonad (Zipper h i b a) where
-- | A 'Coil' is a linked list of the levels above the current one. The length
-- of a 'Coil' is known at compile time.
--
--- This is part of the internal structure of a zipper. You shouldn't need to manipulate this directly.
+-- This is part of the internal structure of a 'Zipper'. You shouldn't need to manipulate this directly.
#ifndef HLINT
data Coil h i t b a where
Coil :: Coil Top Int b b a
@@ -399,8 +399,8 @@ moveToward i z@(Zipper h _ _ p0 j s0)
{-# INLINE moveToward #-}
-- | Move horizontally to a particular index @i@ in the current
--- 'Traversal'. In the case of simple 'Zipper's, the index is 'Int' and
--- we can move between 'Control.Lens.Type.Traversal's fairly easily:
+-- 'Traversal'. In the case of simple zippers, the index is 'Int' and
+-- we can move between traversals fairly easily:
--
-- -- >>> zipper (42, 32) & fromWithin both & moveTo 0 <&> view focus
-- 42
View
30 src/Control/Lens/Internal/Zipper.hs
@@ -176,7 +176,7 @@ magma l f s = magmaOuts bz <$> f (magmaIns bz) where
-- * Paths
--- | A Path into a 'Magma' that ends at a 'Leaf'
+-- | A 'Path' into a 'Magma' that ends at a 'Leaf'.
data Path i a
= ApL Int Bool Bool (Last i) !(Path i a) !(Magma i a)
| ApR Int Bool Bool (Last i) !(Magma i a) !(Path i a)
@@ -189,7 +189,7 @@ instance Functor (Path i) where
fmap _ Start = Start
{-# INLINE fmap #-}
--- | Calculate the absolute position of the leaf targeted by a 'Path'.
+-- | Calculate the absolute position of the 'Leaf' targeted by a 'Path'.
--
-- This can be quite expensive for right-biased traversals such as you
-- receive from a list.
@@ -199,8 +199,8 @@ offset (ApL _ _ _ _ q _) = offset q
offset (ApR _ _ _ _ l q) = size l + offset q
{-# INLINE offset #-}
--- | Return the total number of children in the 'Magma' by walking the path to
--- the root.
+-- | Return the total number of children in the 'Magma' by walking the
+-- 'Path' to the root.
pathsize :: Path i a -> Int
pathsize = go 1 where
go n Start = n
@@ -216,7 +216,7 @@ pathsize = go 1 where
-- "list case", where the traversal tree is right-biased, as in (Ap (Leaf (Identity x))
-- (Ap (Leaf (Identity y)) ...)). It should be safe to delete any of these cases.
--- | Reconstruct a 'Magma' from a 'Path'
+-- | Reconstruct a 'Magma' from a 'Path'.
recompress :: Path i a -> i -> a -> Magma i a
recompress Start i a = Leaf i a -- Unrolled: The lens case.
recompress (ApL m _ _ li Start r) i a = Ap m False False li (Leaf i a) r -- Unrolled: The list case. In particular, a right-biased tree that we haven't moved rightward in.
@@ -249,7 +249,7 @@ startr p0 c0 kn kp = go p0 c0 where
go _ Pure = kn
{-# INLINE startr #-}
--- | Move left one leaf.
+-- | Move left one 'Leaf'.
movel :: Path i a -> Magma i a -> r -> (Path i a -> i -> a -> r) -> r
movel p0 c0 kn kp = go p0 c0 where
go Start _ = kn
@@ -259,7 +259,7 @@ movel p0 c0 kn kp = go p0 c0 where
go (ApL m _ _ li p r) l = go p (Ap m False False li l r)
{-# INLINE movel #-}
--- | Move right one leaf.
+-- | Move right one 'Leaf'.
mover :: Path i a -> Magma i a -> r -> (Path i a -> i -> a -> r) -> r
mover p0 c0 kn kp = go p0 c0 where
go Start _ = kn
@@ -336,7 +336,7 @@ type instance Zipped (Zipper h i s) a = Zipped h s
-- | A 'Coil' is a linked list of the levels above the current one. The length
-- of a 'Coil' is known at compile time.
--
--- This is part of the internal structure of a zipper. You shouldn't need to manipulate this directly.
+-- This is part of the internal structure of a 'Zipper'. You shouldn't need to manipulate this directly.
#ifndef HLINT
data Coil t i a where
Coil :: Coil Top Int a
@@ -348,7 +348,7 @@ focus :: IndexedLens' i (Zipper h i a) a
focus f (Zipper h t o p i a) = Zipper h t o p i <$> indexed f i a
{-# INLINE focus #-}
--- | Construct a 'Zipper' that can explore anything, and start it at the top.
+-- | Construct a 'Zipper' that can explore anything, and start it at the 'Top'.
zipper :: a -> Top :>> a
zipper = Zipper Coil 0 0 Start 0
{-# INLINE zipper #-}
@@ -362,7 +362,7 @@ focalPoint (Zipper _ _ _ _ i _) = i
--
-- @'jerkTo' ('tooth' l) l = Just'@
--
--- Mnemonically, 'Zipper's have a number of 'teeth' within each level. This is which 'tooth' you are currently at.
+-- Mnemonically, zippers have a number of 'teeth' within each level. This is which 'tooth' you are currently at.
--
-- This is based on ordinal position regardless of the underlying index type. It may be excessively expensive for a list.
--
@@ -587,8 +587,8 @@ moveToward i z@(Zipper h _ _ p0 j s0)
{-# INLINE moveToward #-}
-- | Move horizontally to a particular index @i@ in the current
--- 'Traversal'. In the case of simple 'Zipper's, the index is 'Int' and
--- we can move between 'Control.Lens.Type.Traversal's fairly easily:
+-- 'Traversal'. In the case of simple zippers, the index is 'Int' and
+-- we can move between traversals fairly easily:
--
-- >>> zipper (42, 32) & fromWithin both & moveTo 0 <&> view focus
-- 42
@@ -785,17 +785,17 @@ restoreTrack (Fork h n l) = restoreTrack h >=> moveTo n >=> iwithin l
-- | Restore ourselves to a location near our previously recorded position.
--
--- When moving leftward to rightward through a 'Traversal', if this will clamp at each level to the range @0 <= k < teeth@,
+-- When moving 'leftward' to 'rightward' through a 'Traversal', if this will clamp at each level to the range @0 '<=' k '<' 'teeth'@,
-- so the only failures will occur when one of the sequence of downward traversals find no targets.
restoreNearTrack :: MonadPlus m => Track h i a -> Zipped h a -> m (Zipper h i a)
restoreNearTrack Track = return . zipper
restoreNearTrack (Fork h n l) = restoreNearTrack h >=> moveToward n >>> iwithin l
-- | Restore ourselves to a previously recorded position.
--
--- This *assumes* that nothing has been done in the meantime to affect the existence of anything on the entire path.
+-- This *assumes* that nothing has been done in the meantime to affect the existence of anything on the entire 'Path'.
--
--- Motions leftward or rightward are clamped, but all traversals included on the 'Tape' are assumed to be non-empty.
+-- Motions 'leftward' or 'rightward' are clamped, but all traversals included on the 'Tape' are assumed to be non-empty.
--
-- Violate these assumptions at your own risk!
unsafelyRestoreTrack :: Track h i a -> Zipped h a -> Zipper h i a
View
4 src/Control/Lens/Type.hs
@@ -495,10 +495,10 @@ type LensLike f s t a b = (a -> f b) -> s -> f t
-- | @type 'LensLike'' f = 'Simple' ('LensLike' f)@
type LensLike' f s a = LensLike f s s a a
--- | Convenient alias for constructing 'IndexedLens'es and their ilk.
+-- | Convenient alias for constructing indexed lenses and their ilk.
type IndexedLensLike i f s t a b = forall p. Indexable i p => p a (f b) -> s -> f t
--- | Convenient alias for constructing simple 'IndexedLens'es and their ilk.
+-- | Convenient alias for constructing simple indexed lenses and their ilk.
type IndexedLensLike' i f s a = IndexedLensLike i f s s a a
type Lensing p f s t a b = p a (f b) -> s -> f t
View
4 src/Control/Lens/Zipper.hs
@@ -12,7 +12,7 @@
-- The code here is inspired by Brandon Simmons' @zippo@ package, but uses
-- a different approach to represent the 'Zipper' that makes the whole thing
-- look like his breadcrumb trail, and can move side-to-side through
--- 'Control.Lens.Type.Traversal's.
+-- traversals.
--
-- Some examples types:
--
@@ -37,7 +37,7 @@
-- self-similar children in syntax trees and other structures.
--
-- Given keys in ascending order you can jump directly to a given key with
--- 'moveTo'. When used with 'Control.Lens.Type.IndexedTraversal's for balanced
+-- 'moveTo'. When used with traversals for balanced
-- tree-like structures such as an 'Data.IntMap.IntMap' or 'Data.Map.Map',
-- searching for a key with 'moveTo' can be done in logarithmic time.
-----------------------------------------------------------------------------

0 comments on commit 105b1b4

Please sign in to comment.
Something went wrong with that request. Please try again.