Javascript Documentation Generation
If you are only here for jquery.couch.js documentation then go get it quick
I have a bit of an inclination for generating documentation from source code, using as much information that can be infered as possible helps make sure the documentation is up to date, While I have spent a lot of time on Erlang documentation, I hadnt ever run across good generated Javascript documentation.
One of my most commonly used Javascript libraries is the jQuery driver for CouchDB, jquery.couch.js, much like jQuery it has a nice succinct API and is very ‘guessable’ however I still missed documentation from time to time and certainly think it could be easier for new developers, so after some digging around and trying a few options I came across jsdoc-toolkit. A lot of the content came from MC’s excellent CouchDB API Documentation
Documenting javascript is problematic as it has a fairly complex object / prototype model and it doesnt have strong idioms, lots of Javascript source code looks wildly different. I was impressed that I managed to have jsdoc-toolkit generate a sensible structure of documentation from the jquery.couch.js source code without any actual source code changes (excluding inserting comments), This was mostly done with a combination of the @namespace and @lends constructs, for example:
/**
* @namespace
*/
changes: function(since, options) {
options = options || {};
// set up the promise object within a closure for this handler
var timeout = 100, db = this, active = true,
listeners = [],
promise = /** @lends $.couch.db.changes */ {
/**
* Stop subscribing to the changes feed
*/
stop : function() {
active = false;
}
};you can read up the rest of the constructs and documentation on the jsdoc toolkit wiki.
I wasnt particularly happy with the default generated templates generated by jsdoc-toolkit so spent a while customising the output format until I arrived at the following, you can find the templates on my github. Thanks to Andy Chudd who designed the awesome RequireJS Website whos typography I blatantly stole.
