Generate API documentation

[hildjj]

Some combination of jsdoc, tsc, tsdoc, and/or dts-gen.

Separate, related goal: generate .d.ts file, rather than hand-coding

[StoneCypher]

Separate, related goal: generate .d.ts file, rather than hand-coding

So here's a topic

There exists a tool called dts-gen that can do this without typescript. However, it's pretty broad: it'll give fairly minimal type bindings.

If on the other hand you let typescript do this, you get a much stronger type file, but need to get peggy through tsc once first

I guess if it were up to me, I'd slap dts-gen on it now with the intention of switching to better results from tsc down the road, assuming that'd be a little bit of work

Thoughts?

(also should this be a different issue?)

[hildjj]

I think this is the same issue. I'll do a PR for the tsc approach since I've used it before. You do one for dts-gen, then let's compare them and see what we like?

Are we both going to need the same jsdoc type annotations? Maybe we should do that first together.

[StoneCypher]

I'll do a PR for the tsc approach since I've used it before. You do one for dts-gen, then let's compare them and see what we like?

i mean if you're doing it through tsc then that's the good way and there's no reason for the dts-gen way

dts-gen is just a stop-gap. if tsc is already working, it should be that

.

Are we both going to need the same jsdoc type annotations? Maybe we should do that first together.

They both consume the same annotations.

If it's tsc driven, typescript will already know what a lot of them are from static analysis

Personally, I'm going to make an investigation of how much work it would actually be to convert peggy itself to TS. I know, nobody has agreed that that's the right thing to do yet; I just want to sniff around and see what I think.

Obviously, it would need to be delivered as JS at the end.