Elaborate further on ZipList Applicative docs
authorChris Martin <ch.martin@gmail.com>
Sun, 12 Mar 2017 19:15:29 +0000 (15:15 -0400)
committerBen Gamari <ben@smart-cactus.org>
Mon, 13 Mar 2017 17:53:35 +0000 (13:53 -0400)
I was initially confused when I read "zipWithn" in the haddock for
ZipList, went looking for a function named "zipWithn", and found that
it didn't exist. This expands the docs to clarify that we're referring
to the family of functions [zipWith, zipWith3, zipWith4, ...],
capitalizes the letter "n" in "zipWithN" in attempt to make that more
readable, and gives an example.

I also moved this documentation from ZipList itself to the Applicative
instance, so that it will show up in both the Ziplist documentation and
in the list of Applicative instances.

Reviewers: austin, hvr, bgamari

Reviewed By: bgamari

Subscribers: rwbarton, thomie

Differential Revision: https://phabricator.haskell.org/D3324

libraries/base/Control/Applicative.hs

index 406f086..9045bcd 100644 (file)
@@ -99,16 +99,24 @@ instance (ArrowZero a, ArrowPlus a) => Alternative (WrappedArrow a b) where
     empty = WrapArrow zeroArrow
     WrapArrow u <|> WrapArrow v = WrapArrow (u <+> v)
 
--- | Lists, but with an 'Applicative' functor based on zipping, so that
---
--- @f '<$>' 'ZipList' xs1 '<*>' ... '<*>' 'ZipList' xsn = 'ZipList' (zipWithn f xs1 ... xsn)@
---
+-- | Lists, but with an 'Applicative' functor based on zipping.
 newtype ZipList a = ZipList { getZipList :: [a] }
                   deriving ( Show, Eq, Ord, Read, Functor
                            , Foldable, Generic, Generic1)
 -- See Data.Traversable for Traversable instance due to import loops
 
--- | @since 2.01
+-- |
+-- > f '<$>' 'ZipList' xs1 '<*>' ... '<*>' 'ZipList' xsN
+--       = 'ZipList' (zipWithN f xs1 ... xsN)
+--
+-- where @zipWithN@ refers to the @zipWith@ function of the appropriate arity
+-- (@zipWith@, @zipWith3@, @zipWith4@, ...). For example:
+--
+-- > (\a b c -> stimes c [a, b]) <$> ZipList "abcd" <*> ZipList "567" <*> ZipList [1..]
+-- >     = ZipList (zipWith3 (\a b c -> stimes c [a, b]) "abcd" "567" [1..])
+-- >     = ZipList {getZipList = ["a5","b6b6","c7c7c7"]}
+--
+-- @since 2.01
 instance Applicative ZipList where
     pure x = ZipList (repeat x)
     liftA2 f (ZipList xs) (ZipList ys) = ZipList (zipWith f xs ys)