From 9094989b03638199022cd7f3d35dfe0ca0eb37c6 Mon Sep 17 00:00:00 2001
From: Derek Elkins <derek.a.elkins@gmail.com>
Date: Sun, 20 Jan 2008 04:36:10 +0000
Subject: [PATCH] Haddock documentation for Text.Parsec.Char

---
 Text/Parsec/Char.hs | 102 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 88 insertions(+), 14 deletions(-)

diff --git a/Text/Parsec/Char.hs b/Text/Parsec/Char.hs
index 68d5dc9..2e25773 100644
--- a/Text/Parsec/Char.hs
+++ b/Text/Parsec/Char.hs
@@ -20,42 +20,116 @@ import Data.Char
 import Text.Parsec.Pos
 import Text.Parsec.Prim
 
--- | Character parsers
+-- | @oneOf cs@ succeeds if the current character is in the supplied
+-- list of characters @cs@. Returns the parsed character. See also
+-- 'satisfy'.
+-- 
+-- >   vowel  = oneOf "aeiou"
 
-oneOf, noneOf :: (Stream s m Char) => [Char] -> ParsecT s u m Char
+oneOf :: (Stream s m Char) => [Char] -> ParsecT s u m Char
 oneOf cs            = satisfy (\c -> elem c cs)
+
+-- | As the dual of 'oneOf', @noneOf cs@ succeeds if the current
+-- character /not/ in the supplied list of characters @cs@. Returns the
+-- parsed character.
+--
+-- >  consonant = noneOf "aeiou"
+
+noneOf :: (Stream s m Char) => [Char] -> ParsecT s u m Char
 noneOf cs           = satisfy (\c -> not (elem c cs))
 
+-- | Skips /zero/ or more white space characters. See also 'skipMany'.
+
 spaces :: (Stream s m Char) => ParsecT s u m ()
 spaces              = skipMany space        <?> "white space"
 
-space, newline, tab :: (Stream s m Char) => ParsecT s u m Char
-space               = satisfy (isSpace)     <?> "space"
+-- | Parses a white space character (any character which satisfies 'isSpace')
+-- Returns the parsed character. 
+
+space :: (Stream s m Char) => ParsecT s u m Char
+space               = satisfy isSpace       <?> "space"
+
+-- | Parses a newline character (\'\\n\'). Returns a newline character. 
+
+newline :: (Stream s m Char) => ParsecT s u m Char
 newline             = char '\n'             <?> "new-line"
+
+-- | Parses a tab character (\'\\t\'). Returns a tab character. 
+
+tab :: (Stream s m Char) => ParsecT s u m Char
 tab                 = char '\t'             <?> "tab"
 
-upper, lower, alphaNum, letter, digit, hexDigit, octDigit :: (Stream s m Char)
-    => ParsecT s u m Char
-upper               = satisfy (isUpper)     <?> "uppercase letter"
-lower               = satisfy (isLower)     <?> "lowercase letter"
-alphaNum            = satisfy (isAlphaNum)  <?> "letter or digit"
-letter              = satisfy (isAlpha)     <?> "letter"
-digit               = satisfy (isDigit)     <?> "digit"
-hexDigit            = satisfy (isHexDigit)  <?> "hexadecimal digit"
-octDigit            = satisfy (isOctDigit)  <?> "octal digit"
+-- | Parses an upper case letter (a character between \'A\' and \'Z\').
+-- Returns the parsed character. 
+
+upper :: (Stream s m Char) => ParsecT s u m Char
+upper               = satisfy isUpper       <?> "uppercase letter"
+
+-- | Parses a lower case character (a character between \'a\' and \'z\').
+-- Returns the parsed character. 
+
+lower :: (Stream s m Char) => ParsecT s u m Char
+lower               = satisfy isLower       <?> "lowercase letter"
+
+-- | Parses a letter or digit (a character between \'0\' and \'9\').
+-- Returns the parsed character. 
+
+alphaNum :: (Stream s m Char => ParsecT s u m Char)
+alphaNum            = satisfy isAlphaNum    <?> "letter or digit"
+
+-- | Parses a letter (an upper case or lower case character). Returns the
+-- parsed character. 
+
+letter :: (Stream s m Char) => ParsecT s u m Char
+letter              = satisfy isAlpha       <?> "letter"
+
+-- | Parses a digit. Returns the parsed character. 
+
+digit :: (Stream s m Char) => ParsecT s u m Char
+digit               = satisfy isDigit       <?> "digit"
+
+-- | Parses a hexadecimal digit (a digit or a letter between \'a\' and
+-- \'f\' or \'A\' and \'F\'). Returns the parsed character. 
+
+hexDigit :: (Stream s m Char) => ParsecT s u m Char
+hexDigit            = satisfy isHexDigit    <?> "hexadecimal digit"
+
+-- | Parses an octal digit (a character between \'0\' and \'7\'). Returns
+-- the parsed character. 
+
+octDigit :: (Stream s m Char) => ParsecT s u m Char
+octDigit            = satisfy isOctDigit    <?> "octal digit"
+
+-- | @char c@ parses a single character @c@. Returns the parsed
+-- character (i.e. @c@).
+--
+-- >  semiColon  = char ';'
 
 char :: (Stream s m Char) => Char -> ParsecT s u m Char
 char c              = satisfy (==c)  <?> show [c]
 
+-- | This parser succeeds for any character. Returns the parsed character. 
+
 anyChar :: (Stream s m Char) => ParsecT s u m Char
 anyChar             = satisfy (const True)
 
--- | Primitive character parsers
+-- | The parser @satisfy f@ succeeds for any character for which the
+-- supplied function @f@ returns 'True'. Returns the character that is
+-- actually parsed.
+
+-- >  digit     = satisfy isDigit
+-- >  oneOf cs  = satisfy (\c -> c `elem` cs)
 
 satisfy :: (Stream s m Char) => (Char -> Bool) -> ParsecT s u m Char
 satisfy f           = tokenPrim (\c -> show [c])
                                 (\pos c cs -> updatePosChar pos c)
                                 (\c -> if f c then Just c else Nothing)
 
+-- | @string s@ parses a sequence of characters given by @s@. Returns
+-- the parsed string (i.e. @s@).
+--
+-- >  divOrMod    =   string "div" 
+-- >              <|> string "mod"
+
 string :: (Stream s m Char) => String -> ParsecT s u m String
 string s            = tokens show updatePosString s