Elaborate further on ZipList Applicative docs

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

1 files changed, 13 insertions, 5 deletions

diff --git a/libraries/base/Control/Applicative.hs b/libraries/base/Control/Applicative.hs
index 406f086e94..9045bcd742 100644
--- a/libraries/base/Control/Applicative.hs
+++ b/libraries/base/Control/Applicative.hs
@@ -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)