search

guardian / scribe

DEPRECATED: A rich text editor framework for the web platform
http://guardian.github.io/scribe/
Apache License 2.0
3.5k stars 245 forks source link

Add API documentation #60

Open OliverJAsh opened 10 years ago

gpbmike commented 10 years ago

:+1: This would be nice.

OliverJAsh commented 10 years ago

@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 commented 10 years ago

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 commented 9 years ago

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 commented 9 years ago

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.