Improvements to plugin API. Added initial README for authoring plugins.

jsdoc.js

@@ -177,7 +177,10 @@ function main() {
     // allow user-defined plugins to register listeners
     if (env.conf.plugins) {
         for (var i = 0, leni = env.conf.plugins.length; i < leni; i++) {
-            include(env.conf.plugins[i]);
+            var plugin = require(__dirname + '/' + env.conf.plugins[i]);
+            for (var eventName in plugin) {
+                app.jsdoc.parser.on(eventName, plugin[eventName]);
+            }
         }
     }
     

plugins/README.md

@@ -0,0 +1,36 @@
+Adding a Plugin
+----
+
+There are two steps required to install a new plugin:
+
+  # Create a JavaScript module to contain your plugin code.
+  # Include the name of that module in the "plugins" array of `conf.json`.
+
+For example, if your plugin source code was saved in the  "plugins/shout.js"
+file, you would include it in conf.json like so:
+    
+    {
+        "plugins": [
+            "plugins/shout"
+        ]
+    }
+
+Authoring JSDoc 3 Plugins
+----
+
+The plugin system for JSDoc 3 is event-based, meaning you register an interest
+in a specific named-event with a handler function that will be called by JSDoc
+whenever that event occurs. JSDoc will pass an event object into your handler as
+the argument: this can be used to access information about the event.
+
+For example, to handle events fired whenever a new doclet is created by JSDoc,
+you would add a handler for the "newDoclet" event to your plugin's exported
+functions, like so:
+
+    exports.newDoclet = function(e) {
+        // e.doclet will refer to the newly created doclet
+        // you can read and modify properties of that doclet if you wish
+        if (typeof e.doclet.description === 'string') {
+            e.doclet.description = e.doclet.description.toUpperCase();
+        }
+    };

plugins/markdown.js

@@ -1,18 +1,20 @@
 /**
     @overview Translate doclet descriptions from MarkDown into HTML.
+    @module plugins/markdown
+    @author Michael Mathews <micmath@gmail.com>
  */
 
-(function() {
+var mdParser = require('evilstreak/markdown');
 
-    var markdown = require('evilstreak/markdown');
-    
-    app.jsdoc.parser.on('newDoclet', function(e) {
-        if (e.doclet.description) {
-            e.doclet.description = markdown.toHTML(e.doclet.description)
-                .replace( /&amp;/g, "&" ) // because markdown escapes these
-                .replace( /&lt;/g, "<" )
-                .replace( /&gt;/g, ">" );
-        }
-    });
-    
-})();
+/**
+    Translate markdown syntax in a new doclet's description into HTML. Is run
+    by JSDoc 3 whenever a "newDoclet" event fires.
+ */
+exports.newDoclet = function(e) {
+    if (e.doclet.description) {
+        e.doclet.description = mdParser.toHTML(e.doclet.description)
+            .replace( /&amp;/g, "&" ) // because markdown escapes these
+            .replace( /&lt;/g, "<" )
+            .replace( /&gt;/g, ">" );
+    }
+};

plugins/shout.js

@@ -0,0 +1,14 @@
+/**
+    @overview This is just an example.
+    @module plugins/shout
+    @author Michael Mathews <micmath@gmail.com>
+ */
+
+/**
+    Make your descriptions more shoutier.
+ */
+exports.newDoclet = function(e) {
+    if (typeof e.doclet.description === 'string') {
+        e.doclet.description = e.doclet.description.toUpperCase();
+    }
+};