Document public API

[nene]

Every time I fiddle with Recast API I have to dig through the source code to find out which methods are available and which configuration options are possible.

• The README says that there are parse() and print() and even prettyPrint(), but looking at main.js I see there are also run(), types and visit().
• The README hints at some options, but to actually find out which options are supported, one needs to find options.js and even then you won't know whether the option applies to recast.print() or recast.parse() or perhaps some other method.
• The README also tells that recast.print() returns some object with code field... and then somewhere further down the road it turns out that it might also contain map. Perhaps there's something else useful inside it as well?

For start, a link from README to options.js would be great.

I'm open to submitting a PR, though I don't really know all the aspects.

[benjamn]

I absolutely agree, and I apologize for the absence of good documentation. I've tried to keep the API simple enough that it can be used without knowledge of the fine details, but that excuse is ringing less and less true as time goes on.

I'm not sure when I'll have time to write up truly adequate documentation, but I would absolutely take a PR that added a link to options.js to README.md, if you have time.

[adiba]

Just some JSDoc would help a lot. The code already is commented, but not with JSDoc.

[N1kto]

For those seeking more info on API documentation, I found ast-types package README very helpful in terms of documentation source. That package kind of "powers" this one, so its really helpful.