From 000f2a30e0d77932275ac8d2b9d9e51191ff4e03 Mon Sep 17 00:00:00 2001 From: Viktor Dukhovni Date: Sat, 18 Sep 2021 16:58:33 -0400 Subject: Address some Foldable documentation nits - Add link to laws from the class head - Simplify wording of left/right associativity intro paragraph - Avoid needless mention of "endomorphisms" --- libraries/base/Data/Foldable.hs | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) (limited to 'libraries') diff --git a/libraries/base/Data/Foldable.hs b/libraries/base/Data/Foldable.hs index 1a3c3d62f5..59b8a46a24 100644 --- a/libraries/base/Data/Foldable.hs +++ b/libraries/base/Data/Foldable.hs @@ -149,9 +149,11 @@ infix 4 `elem`, `notElem` -- > | Node (Tree a) a (Tree a) -- > deriving Foldable -- --- A more detailed description can be found in the overview section of +-- A more detailed description can be found in the __Overview__ section of -- "Data.Foldable#overview". -- +-- For the class laws see the __Laws__ section of "Data.Foldable#laws". +-- class Foldable t where {-# MINIMAL foldMap | foldr #-} @@ -1517,11 +1519,12 @@ elements in a single pass. -- == Left and right folds -- -- #leftright# --- Merging the contribution of the current element with an accumulator value --- from a partial result is performed by an /operator/ function, either --- explicitly provided by the caller as in `foldr`, implicit count as in --- `length`, or partly implicit as in `foldMap` (where each element is mapped --- into a 'Monoid', and the monoid's `mappend` operator performs the merge). +-- The contribution of each element to the final result is combined with an +-- accumulator via an /operator/ function. The operator may be explicitly +-- provided by the caller as with `foldr` or may be implicit as in `length`. +-- In the case of `foldMap`, the caller provides a function mapping each +-- element into a suitable 'Monoid', which makes it possible to merge the +-- per-element contributions via that monoid's `mappend` function. -- -- A key distinction is between left-associative and right-associative -- folds: @@ -1985,10 +1988,10 @@ elements in a single pass. -- They do have specialised uses, but are best avoided when in doubt. -- -- @ --- 'foldr'' :: (a -> b -> b) -> b -> t a -> b --- `foldl` :: (b -> a -> b) -> b -> t a -> b --- `foldl1` :: (a -> a -> a) -> t a -> a --- `foldrM` :: (Foldable t, Monad m) => (a -> b -> m b) -> b -> t a -> m b +-- 'foldr'' :: Foldable t => (a -> b -> b) -> b -> t a -> b +-- 'foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b +-- 'foldl1' :: Foldable t => (a -> a -> a) -> t a -> a +-- 'foldrM' :: (Foldable t, Monad m) => (a -> b -> m b) -> b -> t a -> m b -- @ -- -- The lazy left-folds (used corecursively) and 'foldrM' (used to sequence @@ -2128,9 +2131,9 @@ elements in a single pass. -- -- > f' x k = \ z -> z `seq` k (f z x) -- --- We see that a lazy 'foldr' of the @g e@ endomorphisms, with @f'@ as as the --- operator, in fact yields a strict left fold, that avoids building a --- deep chain of intermediate thunks: +-- We see that a lazy 'foldr' combining the @g e :: b -> b@ terms, with @f'@ as +-- as the operator evaluated at the base case `z0` yields a strict left fold +-- that avoids building a deep chain of intermediate thunks: -- -- > foldl' f z0 xs = foldr f' id xs z0 -- > where f' x k = \ z -> z `seq` k (f z x) @@ -2338,6 +2341,7 @@ elements in a single pass. -------------- -- $laws +-- #laws# -- -- @Foldable@ instances are expected to satisfy the following laws: -- @@ -2358,7 +2362,7 @@ elements in a single pass. -- but are generally more efficient when defined more directly as: -- -- > sum = foldl' (+) 0 --- > sum = foldl' (*) 1 +-- > product = foldl' (*) 1 -- -- If the type is also a 'Functor' instance, it should satisfy -- -- cgit v1.2.1