[project @ 2004-07-23 13:24:04 by ross]

docs only

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index f6b27c8..71bac07 100644 (file)
--- a/GHC/Base.lhs
+++ b/GHC/Base.lhs
@@ -161,14 +161,22 @@ class  Eq a  where
     x /= y              = not (x == y)
     x == y              = not (x /= y)
 
+-- | The 'Ord' class is used for totally ordered datatypes.
+--
+-- Instances of 'Ord' can be derived for any user-defined
+-- datatype whose constituent types are in 'Ord'.  The declared order
+-- of the constructors in the data declaration determines the ordering
+-- in derived 'Ord' instances.  The 'Ordering' datatype allows a single
+-- comparison to determine the precise ordering of two objects.
+--
+-- Minimal complete definition: either 'compare' or '<='.
+-- Using 'compare' can be more efficient for complex types.
+--
 class  (Eq a) => Ord a  where
     compare             :: a -> a -> Ordering
     (<), (<=), (>), (>=) :: a -> a -> Bool
     max, min            :: a -> a -> a
 
-    -- An instance of Ord should define either 'compare' or '<='.
-    -- Using 'compare' can be more efficient for complex types.
-
     compare x y
        | x == y    = EQ
        | x <= y    = LT        -- NB: must be '<=' not '<' to validate the
@@ -583,10 +591,9 @@ eqString cs1      cs2         = False
 
 \begin{code}
 data Int = I# Int#
--- ^A fixed-precision integer type with at least the range @[-2^29
--- .. 2^29-1]@.  The exact range for a given implementation can be
--- determined by using 'minBound' and 'maxBound' from the 'Bounded'
--- class.
+-- ^A fixed-precision integer type with at least the range @[-2^29 .. 2^29-1]@.
+-- The exact range for a given implementation can be determined by using
+-- 'Prelude.minBound' and 'Prelude.maxBound' from the 'Prelude.Bounded' class.
 
 zeroInt, oneInt, twoInt, maxInt, minInt :: Int
 zeroInt = I# 0#

diff --git a/GHC/Enum.lhs b/GHC/Enum.lhs
index 93af9eb..0f8df4d 100644 (file)
--- a/GHC/Enum.lhs
+++ b/GHC/Enum.lhs
@@ -36,17 +36,66 @@ default ()          -- Double isn't available yet
 %*********************************************************
 
 \begin{code}
+-- | The 'Bounded' class is used to name the upper and lower limits of a
+-- type.  'Ord' is not a superclass of 'Bounded' since types that are not
+-- totally ordered may also have upper and lower bounds.
+--
+-- The 'Bounded' class may be derived for any enumeration type;
+-- 'minBound' is the first constructor listed in the @data@ declaration
+-- and 'maxBound' is the last.
+-- 'Bounded' may also be derived for single-constructor datatypes whose
+-- constituent types are in 'Bounded'.
+
 class  Bounded a  where
     minBound, maxBound :: a
 
+-- | Class 'Enum' defines operations on sequentially ordered types.
+--
+-- The @enumFrom@... methods are used in Haskell's translation of
+-- arithmetic sequences.
+--
+-- Instances of 'Enum' may be derived for any enumeration type (types
+-- whose constructors have no fields); see Chapter 10 of the /Haskell Report/.
+--  
+-- For any type that is an instance of class 'Bounded' as well as 'Enum',
+-- the following should hold:
+--
+-- * The calls @'succ' 'maxBound'@ and @'pred' 'minBound'@ should result in
+--   a runtime error.
+-- 
+-- * 'fromEnum' and 'toEnum' should give a runtime error if the 
+--   result value is not representable in the result type.
+--   For example, @'toEnum' 7 :: 'Bool'@ is an error.
+--
+-- * 'enumFrom' and 'enumFromThen' should be defined with an implicit bound,
+--   thus:
+--
+-- >   enumFrom     x   = enumFromTo     x maxBound
+-- >   enumFromThen x y = enumFromThenTo x y bound
+-- >     where
+-- >       bound | fromEnum y >= fromEnum x = maxBound
+-- >             | otherwise                = minBound
+--
 class  Enum a  where
-    succ, pred         :: a -> a
+    -- | the successor of a value.  For numeric types, 'succ' adds 1.
+    succ               :: a -> a
+    -- | the predecessor of a value.  For numeric types, 'pred' subtracts 1.
+    pred               :: a -> a
+    -- | Convert from an 'Int'.
     toEnum              :: Int -> a
+    -- | Convert to an 'Int'.
+    -- It is implementation-dependent what 'fromEnum' returns when
+    -- applied to a value that is too large to fit in an 'Int'.
     fromEnum            :: a -> Int
-    enumFrom           :: a -> [a]             -- [n..]
-    enumFromThen       :: a -> a -> [a]        -- [n,n'..]
-    enumFromTo         :: a -> a -> [a]        -- [n..m]
-    enumFromThenTo     :: a -> a -> a -> [a]   -- [n,n'..m]
+
+    -- | Used in Haskell's translation of @[n..]@.
+    enumFrom           :: a -> [a]
+    -- | Used in Haskell's translation of @[n,n'..]@.
+    enumFromThen       :: a -> a -> [a]
+    -- | Used in Haskell's translation of @[n..m]@.
+    enumFromTo         :: a -> a -> [a]
+    -- | Used in Haskell's translation of @[n,n'..m]@.
+    enumFromThenTo     :: a -> a -> a -> [a]
 
     succ                  = toEnum . (`plusInt` oneInt)  . fromEnum
     pred                  = toEnum . (`minusInt` oneInt) . fromEnum