From: simonmar <unknown>
Date: Thu, 4 Jul 2002 16:22:03 +0000 (+0000)
Subject: [project @ 2002-07-04 16:22:02 by simonmar]
X-Git-Tag: nhc98-1-18-release~949
X-Git-Url: http://git.megacz.com/?p=ghc-base.git;a=commitdiff_plain;h=789216806265506d3b4637b3b22eb5a46eb5f8f8

[project @ 2002-07-04 16:22:02 by simonmar]
Flesh out the documentation a bit.
---

diff --git a/Data/Either.hs b/Data/Either.hs
index d8a35b5..9fed2d3 100644
--- a/Data/Either.hs
+++ b/Data/Either.hs
@@ -22,6 +22,16 @@ module Data.Either (
 import GHC.Base
 #endif
 
+{-|
+
+The 'Either' type represents values with two possibilities: a value of
+type @'Either' a b@ is either @'Left' a@ or @'Right' b@.
+
+The 'Either' type is sometimes used to represent a value which is
+either correct or an error; by convention, the 'Left' constructor is
+used to hold an error value and the 'Right' constructor is used to
+hold a correct value (mnemonic: \"right\" also means \"correct\").
+-}
 data  Either a b  =  Left a | Right b	deriving (Eq, Ord )
 
 either                  :: (a -> c) -> (b -> c) -> Either a b -> c
diff --git a/Data/Maybe.hs b/Data/Maybe.hs
index 4b7b67e..32101b7 100644
--- a/Data/Maybe.hs
+++ b/Data/Maybe.hs
@@ -38,7 +38,18 @@ import GHC.Base
 -- ---------------------------------------------------------------------------
 -- The Maybe type, and instances
 
-data  Maybe a  =  Nothing | Just a	deriving (Eq, Ord)
+-- | The 'Maybe' type encapsulates an optional value.  A value of type
+-- @'Maybe' a@ either contains a value of type @a@ (represented as @'Just' a@), 
+-- or it is empty (represented as 'Nothing').  Using 'Maybe' is a good way to 
+-- deal with errors or exceptional cases without resorting to drastic
+-- measures such as 'error'.
+--
+-- The 'Maybe' type is also a monad.  It is a simple kind of error
+-- monad, where all errors are represented by 'Nothing'.  A richer
+-- error monad can be built using the 'Data.Either.Either' type.
+
+data  Maybe a  =  Nothing | Just a	
+  deriving (Eq, Ord)
 
 instance  Functor Maybe  where
     fmap _ Nothing       = Nothing
diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index 3945397..9601209 100644
--- a/GHC/Base.lhs
+++ b/GHC/Base.lhs
@@ -149,6 +149,14 @@ unpackCStringUtf8# a = error "urk"
 %*********************************************************
 
 \begin{code}
+
+-- | The 'Eq' class defines equality ('==') and inequality ('/=').
+-- All the basic datatypes exported by the "Prelude" are instances of 'Eq',
+-- and 'Eq' may be derived for any datatype whose constituents are also
+-- instances of 'Eq'.
+--
+-- Minimal complete definition: either '==' or '/='.
+--
 class  Eq a  where
     (==), (/=)		 :: a -> a -> Bool
 
@@ -415,6 +423,8 @@ need ().  (We could arrange suck in () only if -fglasgow-exts, but putting
 it here seems more direct.)
 
 \begin{code}
+-- | The unit datatype @()@ has one non-undefined member, the nullary
+-- constructor @()@.
 data () = ()
 
 instance Eq () where
@@ -439,6 +449,9 @@ instance Ord () where
 %*********************************************************
 
 \begin{code}
+-- | Represents an ordering relationship between two values: less
+-- than, equal to, or greater than.  An 'Ordering' is returned by
+-- 'compare'.
 data Ordering = LT | EQ | GT deriving (Eq, Ord)
 	-- Read in GHC.Read, Show in GHC.Show
 \end{code}
@@ -451,8 +464,18 @@ data Ordering = LT | EQ | GT deriving (Eq, Ord)
 %*********************************************************
 
 \begin{code}
+-- | A 'String' is a list of characters.  String constants in Haskell are values
+-- of type 'String'.
+--
 type String = [Char]
 
+{-| The character type 'Char' is an enumeration whose values represent
+Unicode characters.  A character literal in Haskell has type 'Char'.
+
+To convert a 'Char' to or from an 'Int', use 'Prelude.toEnum' and
+'Prelude.fromEnum' from the 'Enum' class respectively (equivalently
+'ord' and 'chr' also do the trick).
+-}
 data Char = C# Char#
 
 -- We don't use deriving for Eq and Ord, because for Ord the derived
diff --git a/GHC/Float.lhs b/GHC/Float.lhs
index 5c68de4..5c30439 100644
--- a/GHC/Float.lhs
+++ b/GHC/Float.lhs
@@ -98,7 +98,10 @@ class  (RealFrac a, Floating a) => RealFloat a  where
 %*********************************************************
 
 \begin{code}
+-- | Single-precision floating point numbers.
 data Float	= F# Float#
+
+-- | Double-precision floating point numbers.
 data Double	= D# Double#
 
 instance CCallable   Float
diff --git a/GHC/IOBase.lhs b/GHC/IOBase.lhs
index 1497ec9..975bc79 100644
--- a/GHC/IOBase.lhs
+++ b/GHC/IOBase.lhs
@@ -55,6 +55,19 @@ Libraries - parts of hslibs/lang.
 --SDM
 -}
 
+{-|
+A value of type @'IO' a@ is a computation which, when performed,
+does some I\/O before returning a value of type @a@.  
+
+There is really only one way to \"perform\" an I\/O action: bind it to
+@Main.main@ in your program.  When your program is run, the I\/O will
+be performed.  It isn't possible to perform I\/O from an arbitrary
+function, unless that function is itself in the 'IO' monad and called
+at some point, directly or indirectly, from @Main.main@.
+
+'IO' is a monad, so 'IO' actions can be combined using either the do-notation
+or the '>>' and '>>=' operations from the 'Monad' class.
+-}
 newtype IO a = IO (State# RealWorld -> (# State# RealWorld, a #))
 
 unIO :: IO a -> (State# RealWorld -> (# State# RealWorld, a #))
diff --git a/GHC/Num.lhs b/GHC/Num.lhs
index 8e9c662..a0c61e7 100644
--- a/GHC/Num.lhs
+++ b/GHC/Num.lhs
@@ -103,6 +103,7 @@ divModInt x@(I# _) y@(I# _) = (x `divInt` y, x `modInt` y)
 %*********************************************************
 
 \begin{code}
+-- | Arbitrary-precision integers.
 data Integer	
    = S# Int#				-- small integers
 #ifndef ILX
diff --git a/GHC/Real.lhs b/GHC/Real.lhs
index be30073..c2e73c0 100644
--- a/GHC/Real.lhs
+++ b/GHC/Real.lhs
@@ -40,6 +40,10 @@ default ()		-- Double isn't available yet,
 
 \begin{code}
 data  (Integral a)	=> Ratio a = !a :% !a  deriving (Eq)
+
+-- | Arbitrary-precision rational numbers, represented as a ratio of
+-- two 'Integer' values.  A rational number may be constructed using
+-- the '%' operator.
 type  Rational		=  Ratio Integer
 
 infinity, notANumber :: Rational
diff --git a/Prelude.hs b/Prelude.hs
index d920e63..b833edb 100644
--- a/Prelude.hs
+++ b/Prelude.hs
@@ -17,9 +17,34 @@
 
 module Prelude (
 
-	-- List things
-    [] (..),
+    -- * Basic data types
+    Bool(..),
+    Maybe(..),
+    Either(..),
+    Ordering(..), 
+    Char, String, Int, Integer, Float, Double, IO,
+    Rational,
+    []((:), []),
+    
+    module Data.Tuple,
+        -- Includes tuple types + fst, snd, curry, uncurry
+    ()(..),		-- The unit type
+    (->),		-- functions
+    
+    -- * Basic type classes
+    Eq(..),
+    Ord(..), 
+    Enum(..),
+    Bounded(..), 
+    Num(..),
+    Real(..),
+    Integral(..),
+    Fractional(..),
+    Floating(..),
+    RealFrac(..),
+    RealFloat(..),
 
+    -- * List operations
     map, (++), filter, concat,
     head, last, tail, init, null, length, (!!), 
     foldl, foldl1, scanl, scanl1, foldr, foldr1, scanr, scanr1,
@@ -33,14 +58,14 @@ module Prelude (
     lines, words, unlines, unwords,
     sum, product,
 
-        -- Everything from Text.Read and Text.Show
+    -- * Converting to and from @String@
     ReadS, ShowS,
     Read(readsPrec, readList),
     Show(showsPrec, showList, show),
     reads, shows, read, lex, 
     showChar, showString, readParen, showParen,
     
-        -- Everything corresponding to the Report's PreludeIO
+    -- * Simple I\/O operations
     ioError, userError, catch,
     FilePath, IOError,
     putChar,
@@ -49,36 +74,12 @@ module Prelude (
     getLine, getContents, interact,
     readFile, writeFile, appendFile, readIO, readLn,
 
-    Bool(..),
-    Maybe(..),
-    Either(..),
-    Ordering(..), 
-    Char, String, Int, Integer, Float, Double, IO,
-    Rational,
-    []((:), []),
-    
-    module Data.Tuple,
-        -- Includes tuple types + fst, snd, curry, uncurry
-    ()(..),		-- The unit type
-    (->),		-- functions
-    
-    Eq(..),
-    Ord(..), 
-    Enum(..),
-    Bounded(..), 
-    Num(..),
-    Real(..),
-    Integral(..),
-    Fractional(..),
-    Floating(..),
-    RealFrac(..),
-    RealFloat(..),
-
-	-- Monad stuff, from GHC.Base, and defined here
+    -- * Monads
     Monad(..),
     Functor(..), 
     mapM, mapM_, sequence, sequence_, (=<<),
 
+    -- * Miscellaneous functions
     maybe, either,
     (&&), (||), not, otherwise,
     subtract, even, odd, gcd, lcm, (^), (^^),