From bdb59e726260fd7997bca7c536c00a54d027bf48 Mon Sep 17 00:00:00 2001
From: Harendra Kumar <harendra.kumar@gmail.com>
Date: Thu, 20 Dec 2018 19:51:47 +0530
Subject: [PATCH] Update documentation

---
 src/Streamly/List.hs | 62 ++++++++++++++++++++++++++++----------------
 1 file changed, 40 insertions(+), 22 deletions(-)

diff --git a/src/Streamly/List.hs b/src/Streamly/List.hs
index ad8fedbde..210fa2c2f 100644
--- a/src/Streamly/List.hs
+++ b/src/Streamly/List.hs
@@ -22,19 +22,8 @@
 -- better performance compared to @[a]@. Standard list, string and list
 -- comprehension syntax can be used with the 'List' type by enabling
 -- 'OverloadedLists', 'OverloadedStrings' and 'MonadComprehensions' GHC
--- extensions.  If you want to replace streamly lists with standard lists, all
--- you need to do is import these definitions:
---
--- @
--- type List = []
--- pattern Nil <- [] where Nil = []
--- pattern Cons x xs = x : xs
--- infixr 5 `Cons`
--- {-\# COMPLETE Cons, Nil #-}
--- @
---
--- Other than that there would be a slight difference in the 'Show' and
--- 'Read' strings.
+-- extensions.  There would be a slight difference in the 'Show' and 'Read'
+-- strings of streamly list as compared to regular lists.
 --
 -- Conversion to stream types is free, any stream combinator can be used on
 -- lists by converting them to streams.  However, for convenience, this module
@@ -45,9 +34,23 @@
 -- List $ S.map (+ 1) $ toSerial (1 \`Cons\` Nil)
 -- @
 --
--- 'Data.Foldable.toList' from 'Foldable' and 'GHC.Exts.toList' and
--- 'GHC.Exts.fromList' from 'IsList' can also be used to convert to and from
--- standard lists.
+-- To convert a 'List' to regular lists, you can use any of the following:
+--
+-- * @toList . toSerial@ and @toSerial . fromList@
+-- * 'Data.Foldable.toList' from "Data.Foldable"
+-- * 'GHC.Exts.toList' and 'GHC.Exts.fromList' from 'IsList' in "GHC.Exts"
+--
+-- If you have made use of 'Nil' and 'Cons' constructors in the code and you
+-- want to replace streamly lists with standard lists, all you need to do is
+-- import these definitions:
+--
+-- @
+-- type List = []
+-- pattern Nil <- [] where Nil = []
+-- pattern Cons x xs = x : xs
+-- infixr 5 `Cons`
+-- {-\# COMPLETE Cons, Nil #-}
+-- @
 --
 -- See <src/docs/streamly-vs-lists.md> for more details and
 -- <src/test/PureStreams.hs> for comprehensive usage examples.
@@ -61,6 +64,8 @@ module Streamly.List
     , pattern Nil
     , pattern Cons
 #endif
+    -- XXX we may want to use rebindable syntax for variants instead of using
+    -- different types (applicative do and apWith).
     , ZipList (..)
     , fromZipList
     , toZipList
@@ -84,9 +89,16 @@ import qualified Streamly.Streams.StreamK as K
 -- using a stream type the programmer needs to specify the Monad otherwise the
 -- type remains ambiguous.
 --
+-- XXX once we separate consM from IsStream or remove the MonadIO and
+-- MonadBaseControlIO dependency from it, then we can make this an instance of
+-- IsStream and use the regular polymorphic functions on Lists as well. Once
+-- that happens we can change the Show and Read instances as well to use "1 >:
+-- 2 >: nil" etc. or should we use a separate constructor indicating the "List"
+-- type ":>" for better inference?
+--
 -- | @List a@ is a replacement for @[a]@.
 --
--- @since 0.5.3
+-- @since 0.6.0
 newtype List a = List { toSerial :: SerialT Identity a }
     deriving (Show, Read, Eq, Ord, NFData, NFData1
              , Semigroup, Monoid, Functor, Foldable
@@ -108,10 +120,16 @@ instance IsList (List a) where
 -- Patterns
 ------------------------------------------------------------------------------
 
+-- Note: When using the OverloadedLists extension we should be able to pattern
+-- match using the regular list contructors. OverloadedLists uses 'toList' to
+-- perform the pattern match, it should not be too bad as it works lazily in
+-- the Identity monad. We need these patterns only when not using that
+-- extension.
+--
 -- | An empty list constructor and pattern that matches an empty 'List'.
 -- Corresponds to '[]' for Haskell lists.
 --
--- @since 0.5.3
+-- @since 0.6.0
 pattern Nil :: List a
 pattern Nil <- (runIdentity . K.null . toSerial -> True) where
     Nil = List K.nil
@@ -121,7 +139,7 @@ infixr 5 `Cons`
 -- | A list constructor and pattern that deconstructs a 'List' into its head
 -- and tail. Corresponds to ':' for Haskell lists.
 --
--- @since 0.5.3
+-- @since 0.6.0
 pattern Cons :: a -> List a -> List a
 pattern Cons x xs <-
     (fmap (second List) . runIdentity . K.uncons . toSerial
@@ -139,7 +157,7 @@ pattern Cons x xs <-
 -- | Just like 'List' except that it has a zipping 'Applicative' instance
 -- and no 'Monad' instance.
 --
--- @since 0.5.3
+-- @since 0.6.0
 newtype ZipList a = ZipList { toZipSerial :: ZipSerialM Identity a }
     deriving (Show, Read, Eq, Ord, NFData, NFData1
              , Semigroup, Monoid, Functor, Foldable
@@ -159,12 +177,12 @@ instance IsList (ZipList a) where
 
 -- | Convert a 'ZipList' to a regular 'List'
 --
--- @since 0.5.3
+-- @since 0.6.0
 fromZipList :: ZipList a -> List a
 fromZipList = List . K.adapt . toZipSerial
 
 -- | Convert a regular 'List' to a 'ZipList'
 --
--- @since 0.5.3
+-- @since 0.6.0
 toZipList :: List a -> ZipList a
 toZipList = ZipList . K.adapt . toSerial