/wiki/Plugins.wiki

 1#summary Writing and using plugins for JsDoc Toolkit
 2
 3= Introduction =
 4
 5New in Version 2 of !JsDoc Toolkit is the ability to add your own functionality into the core processing of your source code (before it is ever sent to your template). This can be a convenient and portable way to change the way !JsDoc Toolkit works to suit your own needs.
 6
 7== It's Easy ==
 8
 9The interface was designed to be simple. If you are using a plugin, installing it is as easy as saving the plugin file to the `app/plugins directory` - that's it. The plugin will automatically be loaded and used for you.
10
11== API ==
12
13Writing a plugin is also simple. The first step is to create a new text file; you can name it whatever you like. The contents of that plugin file should follow this pattern:
14
15{{{
16JSDOC.PluginManager.registerPlugin(
17    "JSDOC.myPluginName",
18    {
19        onSymbol: function(symbol) {
20            // modify properties of the symbol here
21        }
22    }
23);
24}}}
25
26The call to `JSDOC.PluginManager.registerPlugin` takes two arguments:
27
28  * *yourPluginName* - can be any string you wish, but must be unique among all the plugins being used at any given time: it acts as a registy name for your particular plugin. The dot pattern in the example is just a naming convention, it doesn't refer to any actual code object, I could have just as easily named it "JSDOC-myPluginName" or any other name for that matter.
29  * *functionMap* - an object literal that maps events in the !JsDoc Toolkit process model to a handler function that will be executed each time that event happens. In the example I bind a handler to the `onSymbol` event. That means that every time !JsDoc Toolkit creates a `Symbol` instance the associated function will be called.
30
31== Creating a Function Map ==
32
33The function map binds !JsDoc Toolkit events to functions that will be called when those events occur. In the API example the event names is `onSymbol` which means that whenever a `Symbol` instance is created the function will be called. The argument to that function will be the newly created `Symbol` instance. You can record, modify, add or delete any symbol property within your handler function.
34
35The names of events currently supported by the JSDOC.!PluginManager are...
36
37  * onSymbol - fired every time a new code symbol is created. The handler will be passed a `symbol` argument.
38  * onDocCommentSrc - fired every time comment is found in your source code. The handler will be passed a `comment` argument. You can modify the `comment.src` property of this argument to affect the raw source code of the comment.
39  * onDocCommentTags -
40  * onDocTagSynonym -
41  * onDocTag -
42  * onInit -
43  * onFunctionCall -