[easy] add a few comments to the optimal parser code base for improved clarity

[Cyan4973]

essentially a noop for the compiler-parsable portion of the code base

[edit] so I also left an additional assert() which seems to fire. Let's understand why ...