Changeset 6067

Timestamp:

08/04/05 15:41:44 (3 years ago)

Author:

scook0

svk:copy_cache_prev:

8204

Message:

* Initial stab at some Haddock docs for Parser.hs
* Formatted CodeGen?.hs' poem for Haddock :-)

Location:

src/Pugs

Files:

• AST/Internals.hs (modified) (1 diff)
• CodeGen.hs (modified) (1 diff)
• Lexer.hs (modified) (2 diffs)
• Parser.hs (modified) (4 diffs)

src/Pugs/AST/Internals.hs

@@ -1273 +1273 @@
 readVar _ = return undef
 
+{-|
+The \'empty expression\' is just a no-op ('Noop').
+-}
 emptyExp :: Exp
 emptyExp = Noop

src/Pugs/CodeGen.hs

@@ -4 +4 @@
     Code generation interface.
 
-    I sit beside the fire and think
-    of all that I have seen,
-    of meadow-flowers and butterflies
-    in summers that have been...
+>   I sit beside the fire and think
+>   of all that I have seen,
+>   of meadow-flowers and butterflies
+>   in summers that have been...
 -}
 

src/Pugs/Lexer.hs

@@ -94 +94 @@
     return (c:cs)
 
+{-|
+Match any amount of whitespace (not including newlines), followed by a newline
+(as matched by 'ruleEndOfLine').
+-}
 ruleWhiteSpaceLine :: GenParser Char st ()
 ruleWhiteSpaceLine = do
@@ -99 +103 @@
     ruleEndOfLine
 
+{-|
+Match either a single newline, or EOF (which constitutes the termination of a
+line anyway).
+-}
 ruleEndOfLine :: GenParser Char st ()
 ruleEndOfLine = choice [ do { char '\n'; return () }, eof ]

src/Pugs/Parser.hs

@@ -57 +57 @@
     return $ Pos (mkPos pos1 pos2) (unwrap exp)
 
-mkPos :: SourcePos -> SourcePos -> Pos
+{-|
+Create a Pugs 'Pugs.AST.Pos' (for storing in the AST) from two Parsec
+@SourcePos@ positions, being the start and end respectively of the current
+region.
+-}
+mkPos :: SourcePos -- ^ Starting position of the region
+      -> SourcePos -- ^ Ending position of the region
+      -> Pos
 mkPos pos1 pos2 = MkPos
     { posName         = sourceName pos1 
@@ -123 +130 @@
         rest exp
 
+{-|
+Assert that we're at the beginning of a line, but consume no input (and produce
+no result).
+
+Used by 'ruleDocIntroducer', because POD-style regions must have their \'@=@\'
+at the beginning of a line.
+-}
 ruleBeginOfLine :: RuleParser ()
 ruleBeginOfLine = do
@@ -129 +143 @@
     return ()
 
+{-|
+Match a single \'@=@\', but only if it occurs as the first character of a line.
+-}
 ruleDocIntroducer :: RuleParser Char
 ruleDocIntroducer = (<?> "intro") $ do
@@ -134 +151 @@
     char '='
 
+{-|
+Match \'@=cut@\', followed by a newline (see 'ruleWhiteSpaceLine').
+
+The \'@=@\' must be the first character of the line ('ruleDocIntroducer').
+-}
 ruleDocCut :: RuleParser ()
 ruleDocCut = (<?> "cut") $ do