JSDoc: Javadoc for Javascript
For writing API documentation, there is hardly anything better than (a) either having the documentation inline along with the code or (b) having separate staff do the hard work of keeping the docs up-to-date. Because most of us don't have the luxury of (b), we get to settle for (a).
/**
* Sets or removes an attribute based upon a condition.
*
* @param docroot The containing document
* @param nodes List of DOM nodes or ids in docroot
* @param cond Boolean condition
* @param name Attribute name
* @param val Attribute value (defaults to "true")
*/
SXUTIL.prototype.attr = function(docroot, nodes, cond, name, val) {
// ...
}
JSDoc also handles subclassing, class constants, cross-links between documentation entries and so on. For the full feature list, refer to the JSDoc tag reference.
JSDoc can be invoked either manually, periodically using cron, or even per check-in. For example, in Subversion you can use the post-commit hook to run programs which operate on the checked-in data. Combined with JSDoc's performance, you can maintain always up-to-date docs by simply running JSDoc after each check-in. To give you an idea how fast JSDoc is: On a 3GHz Intel CPU, it processes 3500 lines per second. That is quite an achievement.
