@@ -327,21 +327,20 @@ instance Functor (Initial s) where
327327{-# ANN type Step Fuse #-}
328328data Step s b =
329329 Partial !Int !s
330− -- ^ Partial result with an optional backtrack request.
330+ -- ^ @Partial count state@. The following hold:
331331 --
332− -- @Partial count state@ means a partial result is available which
333− -- can be extracted successfully, @state@ is the opaque state of the
334− -- parser to be supplied to the next invocation of the step operation.
335− -- The current input position is reset to @count@ elements back and any
336− -- input before that is dropped from the backtrack buffer.
332+ -- 1. @extract@ on @state@ would succeed and give a result.
333+ -- 2. Current input stream position is reset to @current position - count@.
334+ -- 3. All input before the new current position is dropped. The parser can
335+ -- never backtrack beyond this position.
337336
338337 | Continue !Int !s
339− -- ^ Need more input with an optional backtrack request.
338+ -- ^ @Continue count state@. The following hold:
340339 --
341− -- @Continue count state@ means the parser has consumed the current input
342− -- but no new result is generated, @state@ is the next state of the parser.
343− -- The current input is retained in the backtrack buffer and the input
344− -- position is reset to @count@ elements back.
340+ -- 1. @extract@ on @state@ would give the last 'Partial' result or throw
341+ -- 'ParseError' if there is none.
342+ -- 2. Current input stream position is reset to @current position - count@.
343+ -- 3. the input is retained in a backtrack buffer.
345344
346345 | Done !Int !b
347346 -- ^ Done with leftover input count and result.
@@ -950,7 +949,7 @@ alt (Parser stepL initialL extractL) (Parser stepR initialR extractR) =
950949 -- restriction helps us make backtracking more efficient, as we do not need
951950 -- to keep the consumed items buffered after a yield. Note that we do not
952951 -- enforce this and if a misbehaving parser does not honor this then we can
953− -- get unexpected results.
952+ -- get unexpected results. XXX Can we detect and flag this?
954953 step (AltParseL cnt st) a = do
955954 r <- stepL st a
956955 case r of