Document peg$ variables and methods within a generated parser

[futagoza]

As mentioned by @felix9 in #526, variables (as well as methods) that are prefixed with peg$ in the generated parser are not exactly well known, with developers only discovering them when they either:

1. dig through the generated parser
2. look through the source for PEG.js
3. find out from another PEG.js developer (the most common case I guess)

Let's fix this with more documentation (the joy 😑), as well as document reserved identifiers within the peg$ namespace (e.g. peg$c is used by actions, tokens, etc) so that developers know what not to overwrite, and hackers know exactly what to overwrite 🤣

• Usable variables
• Usable methods (internal helpers)
• Reserved identifiers not recommended for overwriting
• Examples of what could be accomplished using these

[dmajda]

The peg$ variables and functions were meant as internal. They are tied to the specifics of the PEG.js implementation and the idea was that they can change any time between versions (and they did so in the past). They are definitely not an API!

It may make sense to document the peg$ variables and functions as part of documenting PEG.js internals, but I’d strongly advise against the idea of making them officially available for parser authors and/or plugin writers. It would limit the development of PEG.js in the future. Better to build the API on top of them.

[felix9]

So maybe there should be explicit documentation that "peg$" identifiers are not guaranteed to be stable across releases, and should not be relied upon.