diff --git a/Text/Parcom/Core.hs b/Text/Parcom/Core.hs
--- a/Text/Parcom/Core.hs
+++ b/Text/Parcom/Core.hs
@@ -9,7 +9,7 @@
 , ParcomT, parseT
 , Parcom, parse
 , peek, next, atEnd
-, try, handle
+, try, handle, handleB
 , notFollowedBy
 , (<?>), (<|>), empty
 , Stream, Token, Listish, Textish
@@ -122,14 +122,20 @@
 modifyState :: Monad m => (ParcomState s -> ParcomState s) -> ParcomT s t m ()
 modifyState f = ParcomT $ \s -> return (Right (), f s)
 
--- | Very general error / success handler
--- Each of the error / success branches takes both the old and the new state,
--- so that the branch handler itself can decide whether to backtrack or
--- continue with the new state.
+-- | Wrap a raw parser with error and success handler functions, such that:
+--
+-- * the handlers can choose whether to fail or succeed
+--
+-- * the handlers can choose to backtrack (by returning the previous state) or
+--   consume (by returning the new state).
+--
+-- In order to facilitate this, both the error and success handler functions
+-- accept three arguments: the error or parsed value, respectively; the parser
+-- state before parsing; and the parser state after parsing.
 handle' :: Monad m
-    => ParcomT s t m a
-    -> (ParcomError -> ParcomState s -> ParcomState s -> m (Either ParcomError b, ParcomState s))
-    -> (a -> ParcomState s -> ParcomState s -> m (Either ParcomError b, ParcomState s))
+    => ParcomT s t m a -- ^ The parser we're wrapping
+    -> (ParcomError -> ParcomState s -> ParcomState s -> m (Either ParcomError b, ParcomState s)) -- ^ error handler
+    -> (a -> ParcomState s -> ParcomState s -> m (Either ParcomError b, ParcomState s)) -- ^ success handler
     -> ParcomT s t m b
 handle' p errorH successH = ParcomT $ \s -> do
     (r, s') <- runParcomT p s
@@ -139,6 +145,10 @@
         -- parse succeeded: run success handler
         Right x -> successH x s s'
 
+-- | Wrap a raw parser to allow handling success and failure. The error and
+-- success handlers take the error or parsed value, respectively, and return
+-- a parser that should be applied in the error or success case, respectively.
+-- No backtracking is performed.
 handle :: Monad m
     => ParcomT s t m a
     -> (ParcomError -> ParcomT s t m b)
@@ -147,13 +157,15 @@
 handle p f t =
     handle' p (\e _ s' -> runParcomT (f e) s') (\x _ s' -> runParcomT (t x) s')
 
+-- | Same as 'handle', but backtrack on error (that is, if the raw parser
+-- fails, any input it has consumed is restored.
 handleB :: Monad m
     => ParcomT s t m a
     -> (ParcomError -> ParcomT s t m b)
     -> (a -> ParcomT s t m b)
     -> ParcomT s t m b
 handleB p f t =
-    handle' p (\e s _ -> runParcomT (f e) s) (\x s _ -> runParcomT (t x) s)
+    handle' p (\e s _ -> runParcomT (f e) s) (\x _ s' -> runParcomT (t x) s')
 
 -- | Backtracking modifier; restores the parser state to the previous situation
 -- if the wrapped parser fails.
@@ -181,10 +193,12 @@
 atEnd :: (Monad m, Stream s t) => ParcomT s t m Bool
 atEnd = useState (Stream.atEnd . psStream)
 
+-- | Update a source position to proceed to the next line
 nextLine :: SourcePosition -> SourcePosition
 nextLine s =
     s { posLine = posLine s + 1, posColumn = 1 }
 
+-- | Update a source position to proceed to the next column
 nextColumn :: SourcePosition -> SourcePosition
 nextColumn s =
     s { posColumn = posColumn s + 1 }
diff --git a/parcom-lib.cabal b/parcom-lib.cabal
--- a/parcom-lib.cabal
+++ b/parcom-lib.cabal
@@ -2,7 +2,7 @@
 -- documentation, see http://haskell.org/cabal/users-guide/
 
 name:                parcom-lib
-version:             0.6.0.0
+version:             0.7.0.0
 synopsis:            A simple parser-combinator library, a bit like Parsec but without the frills
 description:         Parcom provides parser combinator functionality in a string-type-agnostic way;
                      it supports strict ByteStrings (with Word8 tokens) and any list type (with