From c39743fe545c5e3b0af5e8e8ba5208d30f463e22 Mon Sep 17 00:00:00 2001
From: ross <unknown>
Date: Fri, 23 Jul 2004 13:24:05 +0000
Subject: [PATCH] [project @ 2004-07-23 13:24:04 by ross] docs only

---
 GHC/Base.lhs |   21 ++++++++++++++-------
 GHC/Enum.lhs |   59 +++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 68 insertions(+), 12 deletions(-)

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index f6b27c8..71bac07 100644
--- 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
--- 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
-- 
1.7.10.4