From 69fc73e75a7f7fe388023d16990e9e701b7384e0 Mon Sep 17 00:00:00 2001
From: Gregor Kleen <gkleen@yggdrasil.li>
Date: Tue, 12 Jan 2016 06:12:17 +0000
Subject: documentation & cleanup

---
 bbcode/src/Text/BBCode.hs | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

(limited to 'bbcode/src')

diff --git a/bbcode/src/Text/BBCode.hs b/bbcode/src/Text/BBCode.hs
index 3828c22..4b2ee6e 100644
--- a/bbcode/src/Text/BBCode.hs
+++ b/bbcode/src/Text/BBCode.hs
@@ -1,6 +1,7 @@
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE DeriveGeneric #-}
 
+-- | An implementation of BBcode parsing 'Text' to a syntax tree (@'Forest' 'BBLabel'@)
 module Text.BBCode
        ( TreeError(..)
        , BBLabel
@@ -29,18 +30,20 @@ import qualified Data.Map as Map
 import Data.CaseInsensitive (CI)
 import qualified Data.CaseInsensitive as CI
 
-data TreeError = ImbalancedTags Text Text
-               | LeftoverClose Text
+-- | Errors in input encountered during parsing of lexed token-stream 
+data TreeError = MismatchedTags Text Text -- ^ Closing tags does not match opening tags
+               | ImbalancedTags Text -- ^ We found an extraneous closing tag
                deriving (Show, Eq, Generic, Typeable)
 
 instance Exception TreeError
 
+-- | The label of our rose-tree nodes carries the tag name and a map of attributes
 type BBLabel = (Text, Map Text (Maybe Text))
 
 matches :: Text -> Text -> Bool
--- ^ @`matches` "open" "close"@ should be true iff @[/close]@ is a valid closing tag for @[open]@
+-- ^ @`matches` "open" "close"@ should be 'True' iff @[/close]@ is a valid closing tag for @[open]@
 --
--- > (==) `on` CI.mk
+-- @ (==) `on` 'CI.mk' @
 matches = (==) `on` CI.mk
 
 rose :: [BBToken] -> Either TreeError (Forest BBLabel)
@@ -57,8 +60,8 @@ rose = fmap Z.toForest . flip rose' (Z.fromForest [])
 
     close :: Text -> TreePos Empty BBLabel -> Either TreeError (TreePos Empty BBLabel)
     close tag pos = do
-      pos' <- maybe (Left $ LeftoverClose tag) Right $ Z.parent pos
+      pos' <- maybe (Left $ ImbalancedTags tag) Right $ Z.parent pos
       let
         pTag = fst $ Z.label pos'
-      unless (pTag `matches` tag) . Left $ ImbalancedTags pTag tag -- The structure shows that this mode of failure is not logically required -- it's just nice to have
+      unless (pTag `matches` tag) . Left $ MismatchedTags pTag tag -- The structure shows that this mode of failure is not logically required -- it's just nice to have
       return $ Z.nextSpace pos'
-- 
cgit v1.2.3