Here at PubNub, we love documentation, as you probably already guessed from our extensive collection of client SDKs and detailed API documentation. Up until now, we’ve been using Markdown mostly for the README-level documentation of the AngularJS library. We are to experimenting with asciidoc now. We also recently discovered the Docco library for creating annotated source code, and instantly fell in love!
You may already be familiar with Docco if you use the Underscore JS library - it’s what powers the Underscore annotated source code feature. We found it to be tremendously helpful as we learned about Underscore internals, and figured we’d try to apply this awesome tool to the PubNub AngularJS library as well!
Using Docco is just about as simple as you can get:
-
Install docco via
npm install -g docco -
Add comments to your JavaScript (or, in our case, CoffeeScript) source code
-
Run
docco source_file.coffeeto generate the HTML documentation! (in a 'docs' directory by default)
Please check out our initial cut of the documentation here at the PubNub AngularJS annotated source code, and let us know what you think! We love the idea of helping developers gain more insight into how this powerful library works, as well as provide an easy way for developers to easily submit changes or updates to the documentation.
Do you have any tips, tricks or best practices that you’d suggest for the PubNub JavaScript frameworks or other SDK’s? Please drop us a line and let us know!