Add API documentation about scribe

[gpbmike]

👍 This would be nice.

[OliverJAsh]

@gpbmike We will get around to this, however if you’re willing to spend 5 minutes looking at the code for the main Scribe object constructor along with our example, you should have no problems getting started. Scribe is very small in comparison to other libraries of its kind.

[OliverJAsh]

I would like to document the API using JSDoc. Tools to generate documentation from JSDoc include dgeni from the Angular team, and dox. The former is much more active but less popular.

[ErisDS]

Whilst I love the concept of inline docs, I've tried out a few of the generators and found them to be a bit limited after a fashion (although I'd not seen dgeni). I imagine those tools are better suited to smaller projects - but if I can forward a suggestion, I've just started using readme.io for managing the Ghost dev docs and am really loving it.

It's not inline / auto-generated but once you have it setup you can add admins and the general public can suggest edits which is much the same as a PR.

Their offering is essentially an entire developer hub centred around docs. It's versioned, has search and the option for a Q&A style discussion area. The benefit I can see is that rather that just API docs, a library of useful examples and plugin documentation could all be built up in the same place.

Just a suggestion though - that kind of thing requires time and commitment :)

Wouldn't be a bad idea to jsDoc the main scribe constructor anyway.

[hmgibson23]

Thanks. I will have a look at readme.io and think about it. I'll designate this as low-hanging fruit, as documenting should be pretty easy to do - if mostly just time-consuming.