Better docs for parser options

[hildjj]

There at least needs to be an example

See: pegjs/pegjs#666

[StoneCypher]

If you would allow it, after the typescript fixing, we could set this up in tsdoc

Then tutorials could be in-boarded and there would be a very clear single place from which to teach

[hildjj]

I'm open to using tsdoc, but I'm not ready to move the whole project to ts to get it, and the current mechanism of hand-maintaining the .d.ts file isn't good enough for the future. If we generate it with tsc and pass the tsdoc comments throught, that might work. Show me a prototype?

[StoneCypher]

but I'm not ready to move the whole project to ts to get it

You don't need to. Also, you really ought to: when I already did it, I drove more than 100 bugs out of peg.

 

the current mechanism of hand-maintaining the .d.ts file isn't good enough for the future

It's a one-liner with dts-gen and should be in npm scripts

 

If we generate it with tsc and pass the tsdoc comments throught, that might work. Show me a prototype?

Will do. Probably next weekend - I mostly can only find time for open source on the weekends right now.

It's actually a pretty easy lift, you'll see. Basically all you do is turn allowJs on in the typescript config, then typescript happily pretends most of it is javascript

Granted you have some bugs to fix then, but that needs to happen anyway

[hildjj]

Nod. I've gotten the first few bits of that working in a few other projects, but had to use jsdoc type annotations, which:

• are only compatible with ts types for the most trivial types
• are incompatible with tsdoc

I'm looking forward to seeing how a dts-gen approach makes those better. Thanks for taking this on. I'm going to assign this to you for the moment, assuming that you're going to fix the original bug along with this workflow after we look at the prototype.

[StoneCypher]

meaning bug 666 about setting context data at runtime?

i was just talking about documentation generation

[hildjj]

OK, I'll start a different bug for doc generation, and fix this one tactically for now.

[hildjj]

See #87