X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=GHC%2FBase.lhs;h=8278dbb90689f67b6d308cf92751169516b997cf;hb=a5d8b45865712ab237eee066f37c667f3574f7ac;hp=7d310b74f40618457b7354477b967eb04871760b;hpb=b73537367458c1307177d60d44b85516b661bd99;p=haskell-directory.git

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index 7d310b7..8278dbb 100644
--- a/GHC/Base.lhs
+++ b/GHC/Base.lhs
@@ -81,6 +81,7 @@ Other Prelude modules are much easier with fewer complex dependencies.
 
 #include "MachDeps.h"
 
+-- #hide
 module GHC.Base
 	(
 	module GHC.Base,
@@ -208,14 +209,22 @@ Instances of 'Functor' should satisfy the following laws:
 > fmap id  ==  id
 > fmap (f . g)  ==  fmap f . fmap g
 
-The instances of 'Functor' for lists, 'Maybe' and 'IO' defined in the "Prelude"
-satisfy these laws.
+The instances of 'Functor' for lists, 'Data.Maybe.Maybe' and 'System.IO.IO'
+defined in the "Prelude" satisfy these laws.
 -}
 
 class  Functor f  where
     fmap        :: (a -> b) -> f a -> f b
 
-{- | The 'Monad' class defines the basic operations over a /monad/.
+{- | The 'Monad' class defines the basic operations over a /monad/,
+a concept from a branch of mathematics known as /category theory/.
+From the perspective of a Haskell programmer, however, it is best to
+think of a monad as an /abstract datatype/ of actions.
+Haskell's @do@ expressions provide a convenient syntax for writing
+monadic expressions.
+
+Minimal complete definition: '>>=' and 'return'.
+
 Instances of 'Monad' should satisfy the following laws:
 
 > return a >>= k  ==  k a
@@ -226,16 +235,26 @@ Instances of both 'Monad' and 'Functor' should additionally satisfy the law:
 
 > fmap f xs  ==  xs >>= return . f
 
-The instances of 'Monad' for lists, 'Maybe' and 'IO' defined in the "Prelude"
-satisfy these laws.
+The instances of 'Monad' for lists, 'Data.Maybe.Maybe' and 'System.IO.IO'
+defined in the "Prelude" satisfy these laws.
 -}
 
 class  Monad m  where
+    -- | Sequentially compose two actions, passing any value produced
+    -- by the first as an argument to the second.
     (>>=)       :: forall a b. m a -> (a -> m b) -> m b
+    -- | Sequentially compose two actions, discarding any value produced
+    -- by the first, like sequencing operators (such as the semicolon)
+    -- in imperative languages.
     (>>)        :: forall a b. m a -> m b -> m b
 	-- Explicit for-alls so that we know what order to
 	-- give type arguments when desugaring
+
+    -- | Inject a value into the monadic type.
     return      :: a -> m a
+    -- | Fail with a message.  This operation is not part of the
+    -- mathematical definition of a monad, but is invoked on pattern-match
+    -- failure in a @do@ expression.
     fail	:: String -> m a
 
     m >> k      = m >>= \_ -> k
@@ -343,8 +362,8 @@ augment g xs = g (:) xs
 "foldr/augment" forall k z xs (g::forall b. (a->b->b) -> b -> b) . 
 		foldr k z (augment g xs) = g k (foldr k z xs)
 
-"foldr/id"    			  foldr (:) [] = \x->x
-"foldr/app"    	[1] forall xs ys. foldr (:) ys xs = xs ++ ys
+"foldr/id"    			  foldr (:) [] = \x  -> x
+"foldr/app"    	[1] forall ys. foldr (:) ys = \xs -> xs ++ ys
 	-- Only activate this from phase 1, because that's
 	-- when we disable the rule that expands (++) into foldr
 
@@ -541,7 +560,8 @@ data Ordering = LT | EQ | GT deriving (Eq, Ord)
 type String = [Char]
 
 {-| The character type 'Char' is an enumeration whose values represent
-Unicode (or equivalently ISO 10646) characters.
+Unicode (or equivalently ISO\/IEC 10646) characters
+(see <http://www.unicode.org/> for details).
 This set extends the ISO 8859-1 (Latin-1) character set
 (the first 256 charachers), which is itself an extension of the ASCII
 character set (the first 128 characters).
@@ -671,9 +691,21 @@ id x			=  x
 lazy :: a -> a
 lazy x = x
 
--- | Assertion function.  This simply ignores its boolean argument.
+-- Assertion function.  This simply ignores its boolean argument.
 -- The compiler may rewrite it to @('assertError' line)@.
 
+-- | If the first argument evaluates to 'True', then the result is the
+-- second argument.  Otherwise an 'AssertionFailed' exception is raised,
+-- containing a 'String' with the source file and line number of the
+-- call to 'assert'.
+--
+-- Assertions can normally be turned on or off with a compiler flag
+-- (for GHC, assertions are normally on unless optimisation is turned on 
+-- with @-O@ or the @-fignore-asserts@
+-- option is given).  When assertions are turned off, the first
+-- argument to 'assert' is ignored, and the second argument is
+-- returned as the result.
+
 -- 	SLPJ: in 5.04 etc 'assert' is in GHC.Prim,
 --	but from Template Haskell onwards it's simply
 --	defined here in Base.lhs