Improved documentation for the parser

Author: jared

lambda-buffers-frontend/src/LambdaBuffers/Frontend/Parsec.hs

@@ -216,6 +216,12 @@ runParser p = runParserT (junk *> p <* eof) ()
 
 -- * Lexical elements
 
+--
+-- - Functions which have @parse@ as a prefix simply parse the token
+--
+--  - Functions which have @token@ as a prefix wrap the corresponding @parse@
+--  function with the 'token' function.
+
 parseModuleNamePart :: Stream s m Char => Parser s m (ModuleNamePart SourceInfo)
 parseModuleNamePart = withSourceInfo . label' "module part name" $ ModuleNamePart <$> pModuleNamePart
 
@@ -391,6 +397,11 @@ parseField :: Stream s m Char => Parser s m (Field SourceInfo)
 parseField = withSourceInfo . label' "record field" $ do
   fn <- tokenFieldName
   _ <- token $ char ':'
+  -- TODO: strictly speaking, there's a bug with this when parsing
+  -- > record A a = { fieldName :-- a }
+  -- since this will parse the @:--@ as @:@ and @--@ will start a comment.
+  -- Technically, the specification says that this should parse as the token
+  -- @:-@, and then the remaining @-@ should parse error.
   Field fn <$> parseTyTopLevel
 
 parseTyDef :: Stream s m Char => Parser s m (TyDef SourceInfo)
@@ -527,9 +538,11 @@ parseImport = label' "import statement" $ do
       mayNames = fmap snd mayBracketSrcInfoAndNames
 
   return $
-    Import isQual modName mayNames mayModAlias $ -- Get the rightmost position of the rightmost parsed token
+    Import isQual modName mayNames mayModAlias $
       srcInfo
         { to =
+            -- Get the rightmost position of the rightmost parsed token
+            -- Note: the 'fromJust' clearly never fails.
             fromJust $
               fmap to mayBracketSrcInfo
                 <|> ( case mayModAlias of