jsdoc3/jsdoc — pull request #164 by hegemonic (2012-08-19 04:25:41+00:00)
Title: Templates should define "exports.publish" instead of a global "publish" function

JSDoc expects templates to define a global `publish` function that publishes the docs. This works fine, but it effectively precludes the following enhancements, all of which I'd love to implement at some point:

+ Create a template that can be subclassed, so child templates can inherit some template functions but override others.
+ Generate output for multiple templates simultaneously.
+ Create a web server that generates individual doc pages on demand, allowing users to switch templates on the fly. (This will be much easier to implement once JSDoc can run on Node.js.)

To add flexibility, I think it would be better for templates to assign the `publish` function to `exports.publish`.

This pull request adds support for this feature and converts the existing templates to use `exports.publish` instead of `publish`. It doesn't remove support for the global `publish` function, so existing user-defined templates will still work; however, it logs a warning if a template relies upon a global `publish` function.

The diffs for the templates' `publish.js` files are misleadingly large. Most of the changes are just whitespace adjustments. I also made a few other changes to address JSHint warnings. I tested the templates by running them against JSDoc, and everything appears to be working as expected.

(The pull request also fixes an unrelated issue with the `jsdoc` shell script's `--debug` option, which wasn't being stripped properly, at least on OS X. I ran into this while I was debugging the other changes.)

I'll wait to merge this until I get some feedback on whether these changes make sense.