[commit: ghc] master: base: Improve the documentation of the enumFrom series of functions (dbc8c0f)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/dbc8c0f8a9a5c307a54f40b51819cc88c1377485/ghc

>---------------------------------------------------------------

commit dbc8c0f8a9a5c307a54f40b51819cc88c1377485
Author: ARJANEN Loïc Jean David <arjanen.loic at gmail.com>
Date:   Sat Jun 16 13:00:33 2018 -0400

    base: Improve the documentation of the enumFrom series of functions
    
    Fixes #15134.
    
    Reviewers: dfeuer, hvr, bgamari
    
    Reviewed By: bgamari
    
    Subscribers: rwbarton, thomie, carter
    
    GHC Trac Issues: #15134
    
    Differential Revision: https://phabricator.haskell.org/D4737


>---------------------------------------------------------------

dbc8c0f8a9a5c307a54f40b51819cc88c1377485
 libraries/base/GHC/Enum.hs | 46 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 42 insertions(+), 4 deletions(-)

diff --git a/libraries/base/GHC/Enum.hs b/libraries/base/GHC/Enum.hs
index 234ccb3..af74f7c 100644
--- a/libraries/base/GHC/Enum.hs
+++ b/libraries/base/GHC/Enum.hs
@@ -92,13 +92,51 @@ class  Enum a   where
     -- applied to a value that is too large to fit in an 'Int'.
     fromEnum            :: a -> Int
 
-    -- | Used in Haskell's translation of @[n..]@.
+    -- | Used in Haskell's translation of @[n..]@ with @[n..] = enumFrom n@,
+    --   a possible implementation being @enumFrom n = n : enumFrom (succ n)@.
+    --   For example:
+    --
+    --     * @enumFrom 4 :: [Integer] = [4,5,6,7,...]@
+    --     * @enumFrom 6 :: [Int] = [6,7,8,9,...,maxBound :: Int]@
     enumFrom            :: a -> [a]
-    -- | Used in Haskell's translation of @[n,n'..]@.
+    -- | Used in Haskell's translation of @[n,n'..]@
+    --   with @[n,n'..] = enumFromThen n n'@, a possible implementation being
+    --   @enumFromThen n n' = n : n' : worker (f x) (f x n')@,
+    --   @worker s v = v : worker s (s v)@, @x = fromEnum n' - fromEnum n@ and
+    --   @f n y
+    --     | n > 0 = f (n - 1) (succ y)
+    --     | n < 0 = f (n + 1) (pred y)
+    --     | otherwise = y@
+    --   For example:
+    --
+    --     * @enumFromThen 4 6 :: [Integer] = [4,6,8,10...]@
+    --     * @enumFromThen 6 2 :: [Int] = [6,2,-2,-6,...,minBound :: Int]@
     enumFromThen        :: a -> a -> [a]
-    -- | Used in Haskell's translation of @[n..m]@.
+    -- | Used in Haskell's translation of @[n..m]@ with
+    --   @[n..m] = enumFromTo n m@, a possible implementation being
+    --   @enumFromTo n m
+    --      | n <= m = n : enumFromTo (succ n) m
+    --      | otherwise = []@.
+    --   For example:
+    --
+    --     * @enumFromTo 6 10 :: [Int] = [6,7,8,9,10]@
+    --     * @enumFromTo 42 1 :: [Integer] = []@
     enumFromTo          :: a -> a -> [a]
-    -- | Used in Haskell's translation of @[n,n'..m]@.
+    -- | Used in Haskell's translation of @[n,n'..m]@ with
+    --   @[n,n'..m] = enumFromThenTo n n' m@, a possible implementation
+    --   being @enumFromThenTo n n' m = worker (f x) (c x) n m@,
+    --   @x = fromEnum n' - fromEnum n@, @c x = bool (>=) (<=) (x > 0)@
+    --   @f n y
+    --      | n > 0 = f (n - 1) (succ y)
+    --      | n < 0 = f (n + 1) (pred y)
+    --      | otherwise = y@ and
+    --   @worker s c v m
+    --      | c v m = v : worker s c (s v) m
+    --      | otherwise = []@
+    --   For example:
+    --
+    --     * @enumFromThenTo 4 2 -6 :: [Integer] = [4,2,0,-2,-4,-6]@
+    --     * @enumFromThenTo 6 8 2 :: [Int] = []@
     enumFromThenTo      :: a -> a -> a -> [a]
 
     succ                   = toEnum . (+ 1)  . fromEnum