First pass at improving the Scaladoc comments. #37
Conversation
|
(On reading it here I notice the prose is fairly clunky in some places. I plan to do another pass before I remove the "wip" title -- feel free to comment on any problems you notice but as far as typos or misspellings you can also wait until it's closer to ready.) |
| * `x` returns an epsilon failure; these methods cannot recover from | ||
| * an arresting failure. Arresting failures can be "rewound" using | ||
| * methods such as `backtrack` or `softProduct`, which converts | ||
| * arresting failures into epsilon failures. Since rewinding is |
There was a problem hiding this comment.
Rewinding is actually cheap, but backtracking can result in exponential complexity and tends to make errors harder to locate.
| * - Arresting failure: The parser fails to extract a value but does | ||
| * consume one-or-more characters of input. The input offset will | ||
| * be moved forward by the number of characters consumed. The | ||
| * consumed characters will not be available to any additional |
There was a problem hiding this comment.
The "will not be available" but isn't great wording IMO. After an arresting error, nothing more will be parsed, full stop. It will always be returned to the user.
| * Operations such as `x.orElse(y)` will only consider parser `y` if | ||
| * `x` returns an epsilon failure; these methods cannot recover from | ||
| * an arresting failure. Arresting failures can be "rewound" using | ||
| * methods such as `backtrack` or `softProduct`, which converts |
There was a problem hiding this comment.
This isn't quite right about softProduct. SoftProduct makes a success in the first followed by an epsilon failure in the second into an epsilon failure of the whole thing. By contrast, a normal product the first may have consumed and thus you have an arresting failure even though the second item was an epsilon.
| * This method will return a failure unless all of `str` is consumed | ||
| * during parsing. | ||
| * | ||
| * `p.parseAll(s)` is equivalent to `(p <* * Parser.end).parse(s).map(_._2)`. |
There was a problem hiding this comment.
There is an extra * before Parser.end.
| * epsilon failure. The `?` method converts these failures into | ||
| * None values (and wraps other values in `Some(_)`). | ||
| * | ||
| * If the underlying parser failed with other errors, this parser |
There was a problem hiding this comment.
Do you want to say "arresting error" here?
| * When parsing an input string that the underlying parser matches, | ||
| * this parser will return the matched substring instead of any | ||
| * value that the underlying parser would have returned. It will | ||
| * still match exactly the same inputs as the original parser. |
There was a problem hiding this comment.
You might mention this is very efficient and the same as .void.string internally.
| */ | ||
| /** | ||
| * If this parser fails to match, rewind the offset to the starting | ||
| * point before moving on to other parser. |
There was a problem hiding this comment.
I would say "convert an arresting failure into an epsilon failure" at some point.
| * Otherwise both extracted values are combined into a tuple. | ||
| * | ||
| * Backtracking may be used on the left parser to allow the right | ||
| * one to pick up after an error. |
There was a problem hiding this comment.
This isn't quite right. If A fails B can never run, the only question is will you have an epsilon or arresting failure. If A needs backtracking but B does not, you might do A.backtrack ~ B which is different from (A ~ B).backtrack
| * current parser would fail | ||
| */ | ||
| /** | ||
| * Return a parses that succeeds (consuming nothing, and extracting |
non
changed the title
I'm trying to work through and write more descriptive Scaladoc comments.
In particular, I've coined the term arresting failure to contrast with epsilon failure. I think this makes a lot of the prose easier to follow.
What do you think? cc @johnynek @rossabaker