Permalink
Browse files

haddocks: more linking

  • Loading branch information...
1 parent 31c05a9 commit a142679d6acfb91c317ee9334050df7c449a7820 @basdirks basdirks committed Jan 5, 2013
Showing with 50 additions and 50 deletions.
  1. +1 −1 src/Control/Lens/Each.hs
  2. +4 −4 src/Control/Lens/Equality.hs
  3. +39 −39 src/Control/Lens/Fold.hs
  4. +6 −6 src/Control/Lens/Type.hs
View
@@ -67,7 +67,7 @@ import Data.Array.IArray as IArray
-- >>> (1,2,3) & each *~ 10
-- (10,20,30)
--
--- It can also be used on monomorphic containers like 'StrictT.Text' or 'StrictB.ByteString'
+-- It can also be used on monomorphic containers like 'StrictT.Text' or 'StrictB.ByteString'.
--
-- >>> over each Char.toUpper ("hello"^.Text.packed)
-- "HELLO"
@@ -43,23 +43,23 @@ type AnEquality s t a b = Identical a (Mutator b) a (Mutator b) -> Identical a (
-- | A 'Simple' 'AnEquality'
type AnEquality' s a = AnEquality s s a a
--- | Extract a witness of type equality
+-- | Extract a witness of type equality.
runEq :: AnEquality s t a b -> Identical s t a b
runEq l = case l Identical of Identical -> Identical
{-# INLINE runEq #-}
--- | Substituting types with equality
+-- | Substituting types with equality.
substEq :: AnEquality s t a b -> ((s ~ a, t ~ b) => r) -> r
substEq l = case runEq l of
Identical -> \r -> r
{-# INLINE substEq #-}
--- | We can use equality to do substitution into anything
+-- | We can use equality to do substitution into anything.
mapEq :: AnEquality s t a b -> f s -> f a
mapEq l r = substEq l r
{-# INLINE mapEq #-}
--- | Equality is symmetric
+-- | Equality is symmetric.
fromEq :: AnEquality s t a b -> Equality b a t s
fromEq l = substEq l id
{-# INLINE fromEq #-}
View
@@ -18,7 +18,7 @@
-- A @'Fold' s a@ is a generalization of something 'Foldable'. It allows
-- you to extract multiple results from a container. A 'Foldable' container
-- can be characterized by the behavior of
--- @foldMap :: ('Foldable' t, 'Monoid' m) => (a -> m) -> t a -> m@.
+-- @'Data.Foldable.foldMap' :: ('Foldable' t, 'Monoid' m) => (a -> m) -> t a -> m@.
-- Since we want to be able to work with monomorphic containers, we could
-- generalize this signature to @forall m. 'Monoid' m => (a -> m) -> s -> m@,
-- and then decorate it with 'Accessor' to obtain
@@ -189,7 +189,7 @@ repeated :: Fold a a
repeated f a = as where as = f a *> as
{-# INLINE repeated #-}
--- | A fold that replicates its input @n@ times.
+-- | A 'Fold' that replicates its input @n@ times.
--
-- @'replicate' n ≡ 'toListOf' ('replicated' n)@
--
@@ -202,15 +202,15 @@ replicated n0 f a = go n0 where
go n = m *> go (n - 1)
{-# INLINE replicated #-}
--- | Transform a fold into a fold that loops over its elements over and over.
+-- | Transform a 'Fold' into a 'Fold' that loops over its elements over and over.
--
-- >>> timingOut $ [1,2,3]^..taking 7 (cycled traverse)
-- [1,2,3,1,2,3,1]
cycled :: (Applicative f, Gettable f) => LensLike f s t a b -> LensLike f s t a b
cycled l f a = as where as = l f a *> as
{-# INLINE cycled #-}
--- | Build a fold that unfolds its values from a seed.
+-- | Build a 'Fold' that unfolds its values from a seed.
--
-- @'Prelude.unfoldr' ≡ 'toListOf' . 'unfolded'@
--
@@ -223,21 +223,21 @@ unfolded f g b0 = go b0 where
Nothing -> noEffect
{-# INLINE unfolded #-}
--- | @x ^. 'iterated' f@ Return an infinite fold of repeated applications of @f@ to @x@.
+-- | @x '^.' 'iterated' f@ Return an infinite fold of repeated applications of @f@ to @x@.
--
-- @'toListOf' ('iterated' f) a ≡ 'iterate' f a@
iterated :: (a -> a) -> Fold a a
iterated f g a0 = go a0 where
go a = g a *> go (f a)
{-# INLINE iterated #-}
--- | Obtain a 'Fold' that can be composed with to filter another 'Lens', 'Iso', 'Getter', 'Fold' (or 'Traversal')
+-- | Obtain a 'Fold' that can be composed with to filter another 'Lens', 'Iso', 'Getter', 'Fold' (or 'Traversal').
--
-- Note: This is /not/ a legal 'Traversal', unless you are very careful not to invalidate the predicate on the target.
--
-- As a counter example, consider that given @evens = 'filtered' 'even'@ the second 'Traversal' law is violated:
--
--- @'over' evens 'succ' '.' 'over' evens 'succ' /= 'over' evens ('succ' '.' 'succ')@
+-- @'Control.Lens.Setter.over' evens 'succ' '.' 'Control.Lens.Setter.over' evens 'succ' /= 'Control.Lens.Setter.over' evens ('succ' '.' 'succ')@
--
-- So, in order for this to qualify as a legal 'Traversal' you can only use it for actions that preserve the result of the predicate!
--
@@ -609,7 +609,7 @@ sumOf :: Profunctor q => Overloading (->) q (Accessor (Sum a)) s t a b -> q s a
sumOf l = getSum #. foldMapOf l Sum
{-# INLINE sumOf #-}
--- | Traverse over all of the targets of a 'Fold' (or 'Getter'), computing an 'Applicative' (or 'Functor') -based answer,
+-- | Traverse over all of the targets of a 'Fold' (or 'Getter'), computing an 'Applicative' (or 'Functor')-based answer,
-- but unlike 'Control.Lens.Traversal.traverseOf' do not construct a new structure. 'traverseOf_' generalizes
-- 'Data.Foldable.traverse_' to work over any 'Fold'.
--
@@ -643,7 +643,7 @@ traverseOf_ :: (Profunctor p, Profunctor q, Functor f) => Overloading p q (Acces
traverseOf_ l f = getTraversed #. foldMapOf l (rmap (Traversed #. void) f)
{-# INLINE traverseOf_ #-}
--- | Traverse over all of the targets of a 'Fold' (or 'Getter'), computing an 'Applicative' (or 'Functor') -based answer,
+-- | Traverse over all of the targets of a 'Fold' (or 'Getter'), computing an 'Applicative' (or 'Functor')-based answer,
-- but unlike 'Control.Lens.Traversal.forOf' do not construct a new structure. 'forOf_' generalizes
-- 'Data.Foldable.for_' to work over any 'Fold'.
--
@@ -919,7 +919,7 @@ lastOf l = foldlOf l (\_ y -> Just y) Nothing
-- |
-- Returns 'True' if this 'Fold' or 'Traversal' has no targets in the given container.
--
--- Note: 'nullOf' on a valid 'Iso', 'Lens' or 'Getter' should always return 'False'
+-- Note: 'nullOf' on a valid 'Iso', 'Lens' or 'Getter' should always return 'False'.
--
-- @'null' ≡ 'nullOf' 'folded'@
--
@@ -945,11 +945,11 @@ nullOf l = getAll #. foldMapOf l (\_ -> All False)
-- |
-- Returns 'True' if this 'Fold' or 'Traversal' has any targets in the given container.
--
--- Note: 'notNullOf' on a valid 'Iso', 'Lens' or 'Getter' should always return 'True'
+-- Note: 'notNullOf' on a valid 'Iso', 'Lens' or 'Getter' should always return 'True'.
--
-- @'null' ≡ 'notNullOf' 'folded'@
--
--- This may be rather inefficient compared to the @'not' . 'null'@ check of many containers.
+-- This may be rather inefficient compared to the @'not' '.' 'null'@ check of many containers.
--
-- >>> notNullOf _1 (1,2)
-- True
@@ -968,7 +968,7 @@ notNullOf l = getAny #. foldMapOf l (\_ -> Any True)
{-# INLINE notNullOf #-}
-- |
--- Obtain the maximum element (if any) targeted by a 'Fold' or 'Traversal'
+-- Obtain the maximum element (if any) targeted by a 'Fold' or 'Traversal'.
--
-- Note: 'maximumOf' on a valid 'Iso', 'Lens' or 'Getter' will always return 'Just' a value.
--
@@ -986,7 +986,7 @@ maximumOf l = getMax `rmap` foldMapOf l Max
{-# INLINE maximumOf #-}
-- |
--- Obtain the minimum element (if any) targeted by a 'Fold' or 'Traversal'
+-- Obtain the minimum element (if any) targeted by a 'Fold' or 'Traversal'.
--
-- Note: 'minimumOf' on a valid 'Iso', 'Lens' or 'Getter' will always return 'Just' a value.
--
@@ -1090,7 +1090,7 @@ foldr1Of l f xs = fromMaybe (error "foldr1Of: empty structure")
{-# INLINE foldr1Of #-}
-- | A variant of 'foldlOf' that has no base case and thus may only be applied to lenses and structures such
--- that the lens views at least one element of the structure.
+-- that the 'Lens' views at least one element of the structure.
--
-- @
-- 'foldl1Of' l f ≡ 'Prelude.foldl1Of' l f . 'toList'
@@ -1180,7 +1180,7 @@ foldlMOf l f z0 xs = foldrOf l f' return xs z0
where f' x k z = f z x >>= k
{-# INLINE foldlMOf #-}
--- | Check to see if this 'Fold' or 'Traversal' matches 1 or more entries
+-- | Check to see if this 'Fold' or 'Traversal' matches 1 or more entries.
--
-- >>> has (element 0) []
-- False
@@ -1191,7 +1191,7 @@ foldlMOf l f z0 xs = foldrOf l f' return xs z0
-- >>> has _right (Left 12)
-- False
--
--- This will always return True for a 'Lens' or 'Getter'
+-- This will always return 'True' for a 'Lens' or 'Getter'.
--
-- >>> has _1 ("hello","world")
-- True
@@ -1241,11 +1241,11 @@ hasn't l = getAll #. foldMapOf l (\_ -> All False)
-- a monad transformer stack:
--
-- @
--- 'preview' :: MonadReader s m => 'Getter' s a -> m ('Maybe' a)
--- 'preview' :: MonadReader s m => 'Fold' s a -> m ('Maybe' a)
--- 'preview' :: MonadReader s m => 'Lens'' s a -> m ('Maybe' a)
--- 'preview' :: MonadReader s m => 'Iso'' s a -> m ('Maybe' a)
--- 'preview' :: MonadReader s m => 'Traversal'' s a -> m ('Maybe' a)
+-- 'preview' :: 'MonadReader' s m => 'Getter' s a -> m ('Maybe' a)
+-- 'preview' :: 'MonadReader' s m => 'Fold' s a -> m ('Maybe' a)
+-- 'preview' :: 'MonadReader' s m => 'Lens'' s a -> m ('Maybe' a)
+-- 'preview' :: 'MonadReader' s m => 'Iso'' s a -> m ('Maybe' a)
+-- 'preview' :: 'MonadReader' s m => 'Traversal'' s a -> m ('Maybe' a)
-- @
preview :: MonadReader s m => Getting (Endo (Maybe a)) s t a b -> m (Maybe a)
preview l = asks (foldrOf l (\x _ -> Just x) Nothing)
@@ -1268,11 +1268,11 @@ preview l = asks (foldrOf l (\x _ -> Just x) Nothing)
-- a monad transformer stack:
--
-- @
--- 'previews' :: MonadReader s m => 'Getter' s a -> (a -> r) -> m ('Maybe' r)
--- 'previews' :: MonadReader s m => 'Fold' s a -> (a -> r) -> m ('Maybe' r)
--- 'previews' :: MonadReader s m => 'Lens'' s a -> (a -> r) -> m ('Maybe' r)
--- 'previews' :: MonadReader s m => 'Iso'' s a -> (a -> r) -> m ('Maybe' r)
--- 'previews' :: MonadReader s m => 'Traversal'' s a -> (a -> r) -> m ('Maybe' r)
+-- 'previews' :: 'MonadReader' s m => 'Getter' s a -> (a -> r) -> m ('Maybe' r)
+-- 'previews' :: 'MonadReader' s m => 'Fold' s a -> (a -> r) -> m ('Maybe' r)
+-- 'previews' :: 'MonadReader' s m => 'Lens'' s a -> (a -> r) -> m ('Maybe' r)
+-- 'previews' :: 'MonadReader' s m => 'Iso'' s a -> (a -> r) -> m ('Maybe' r)
+-- 'previews' :: 'MonadReader' s m => 'Traversal'' s a -> (a -> r) -> m ('Maybe' r)
-- @
previews :: MonadReader s m => Getting (Endo (Maybe r)) s t a b -> (a -> r) -> m (Maybe r)
previews l f = asks (foldrOf l (\x _ -> Just (f x)) Nothing)
@@ -1287,11 +1287,11 @@ previews l f = asks (foldrOf l (\x _ -> Just (f x)) Nothing)
-- from a 'Getter' or 'Lens') into the current state.
--
-- @
--- 'preuse' :: MonadState s m => 'Getter' s a -> m ('Maybe' a)
--- 'preuse' :: MonadState s m => 'Fold' s a -> m ('Maybe' a)
--- 'preuse' :: MonadState s m => 'Lens'' s a -> m ('Maybe' a)
--- 'preuse' :: MonadState s m => 'Iso'' s a -> m ('Maybe' a)
--- 'preuse' :: MonadState s m => 'Traversal'' s a -> m ('Maybe' a)
+-- 'preuse' :: 'MonadState' s m => 'Getter' s a -> m ('Maybe' a)
+-- 'preuse' :: 'MonadState' s m => 'Fold' s a -> m ('Maybe' a)
+-- 'preuse' :: 'MonadState' s m => 'Lens'' s a -> m ('Maybe' a)
+-- 'preuse' :: 'MonadState' s m => 'Iso'' s a -> m ('Maybe' a)
+-- 'preuse' :: 'MonadState' s m => 'Traversal'' s a -> m ('Maybe' a)
-- @
preuse :: MonadState s m => Getting (Endo (Maybe a)) s t a b -> m (Maybe a)
preuse l = gets (preview l)
@@ -1301,11 +1301,11 @@ preuse l = gets (preview l)
-- 'Traversal' (or 'Just' the result from a 'Getter' or 'Lens') into the current state.
--
-- @
--- 'preuses' :: MonadState s m => 'Getter' s a -> (a -> r) -> m ('Maybe' r)
--- 'preuses' :: MonadState s m => 'Fold' s a -> (a -> r) -> m ('Maybe' r)
--- 'preuses' :: MonadState s m => 'Lens'' s a -> (a -> r) -> m ('Maybe' r)
--- 'preuses' :: MonadState s m => 'Iso'' s a -> (a -> r) -> m ('Maybe' r)
--- 'preuses' :: MonadState s m => 'Traversal'' s a -> (a -> r) -> m ('Maybe' r)
+-- 'preuses' :: 'MonadState' s m => 'Getter' s a -> (a -> r) -> m ('Maybe' r)
+-- 'preuses' :: 'MonadState' s m => 'Fold' s a -> (a -> r) -> m ('Maybe' r)
+-- 'preuses' :: 'MonadState' s m => 'Lens'' s a -> (a -> r) -> m ('Maybe' r)
+-- 'preuses' :: 'MonadState' s m => 'Iso'' s a -> (a -> r) -> m ('Maybe' r)
+-- 'preuses' :: 'MonadState' s m => 'Traversal'' s a -> (a -> r) -> m ('Maybe' r)
-- @
preuses :: MonadState s m => Getting (Endo (Maybe r)) s t a b -> (a -> r) -> m (Maybe r)
preuses l f = gets (previews l f)
@@ -1626,7 +1626,7 @@ itoListOf :: Profunctor q => Overloading (Indexed i) q (Accessor (Endo [(i,a)]))
itoListOf l = ifoldrOf l (\i a -> ((i,a):)) []
{-# INLINE itoListOf #-}
--- | An infix version of 'itoListOf'
+-- | An infix version of 'itoListOf'.
-- @
-- ('^@..') :: s -> 'IndexedGetter' i s a -> [(i,a)]
@@ -1731,7 +1731,7 @@ idroppingWhile p l f = (flip evalState True .# getCompose) `rmap` l g where
-- Deprecated
------------------------------------------------------------------------------
--- | A deprecated alias for 'firstOf'
+-- | A deprecated alias for 'firstOf'.
headOf :: Profunctor q => Overloading (->) q (Accessor (First a)) s t a b -> q s (Maybe a)
headOf l = getFirst #. foldMapOf l (First #. Just)
{-# INLINE headOf #-}
View
@@ -348,7 +348,7 @@ type Prism' s a = Prism s s a a
-- Equality
-------------------------------------------------------------------------------
--- | A witness that @(a ~ s, b ~ t)@
+-- | A witness that @(a ~ s, b ~ t)@.
--
-- Note: Composition with an 'Equality' is index-preserving.
type Equality s t a b = forall p (f :: * -> *). p a (f b) -> p s (f t)
@@ -385,19 +385,19 @@ type IndexPreservingGetter s a = forall p f. (SelfAdjoint p, Gettable f) => p a
-- | A 'Fold' describes how to retrieve multiple values in a way that can be composed
-- with other lens-like constructions.
--
--- A @'Fold' s a@ provides a structure with operations very similar to those of the 'Foldable'
--- typeclass, see 'foldMapOf' and the other 'Fold' combinators.
+-- A @'Fold' s a@ provides a structure with operations very similar to those of the 'Data.Foldable.Foldable'
+-- typeclass, see 'Control.Lens.Fold.foldMapOf' and the other 'Fold' combinators.
--
--- By convention, if there exists a 'foo' method that expects a @'Foldable' (f a)@, then there should be a
+-- By convention, if there exists a 'foo' method that expects a @'Data.Foldable.Foldable' (f a)@, then there should be a
-- @fooOf@ method that takes a @'Fold' s a@ and a value of type @s@.
--
--- A 'Getter' is a legal 'Fold' that just ignores the supplied 'Monoid'
+-- A 'Getter' is a legal 'Fold' that just ignores the supplied 'Data.Monoid.Monoid'.
--
-- Unlike a 'Control.Lens.Traversal.Traversal' a 'Fold' is read-only. Since a 'Fold' cannot be used to write back
-- there are no lens laws that apply.
type Fold s a = forall f. (Gettable f, Applicative f) => (a -> f a) -> s -> f s
--- | Every 'IndexedFold' is a valid 'Control.Lens.Fold.Fold' and can be used for 'Getting'.
+-- | Every 'IndexedFold' is a valid 'Control.Lens.Fold.Fold' and can be used for 'Control.Lens.Getter.Getting'.
type IndexedFold i s a = forall p f. (Indexable i p, Applicative f, Gettable f) => p a (f a) -> s -> f s
-- | An 'IndexPreservingFold' can be used as a 'Fold', but when composed with an 'IndexedTraversal',

0 comments on commit a142679

Please sign in to comment.