You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<h2id="creating-and-enabling-a-plugin">Creating and Enabling a Plugin</h2>
49
49
<p>There are two steps required to create and enable a new JSDoc plugin:</p>
50
50
<ol>
51
51
<li>Create a JavaScript module to contain your plugin code.</li>
52
-
<li>Include that module in the <code>plugins</code> array of <code>conf.json</code>. You can specify an absolute or relative path. If you use a relative path,
53
-
JSDoc searches for the plugin in the current working directory and the JSDoc directory, in that order.</li>
52
+
<li>Include that module in the <code>plugins</code> array of <ahref="about-configuring-jsdoc.html">JSDoc's configuration file</a>. You can specify an absolute
53
+
or relative path. If you use a relative path, JSDoc searches for the plugin in the directory where the configuration file is located; the current working
54
+
directory; and the JSDoc directory, in that order.</li>
54
55
</ol>
55
-
<p>For example, if your plugin source code was saved in the <code>plugins/shout.js</code> file in the current working directory, you would include it by adding
56
-
a reference to it in <code>conf.json</code> like so:</p>
56
+
<p>For example, if your plugin is defined in the <code>plugins/shout.js</code> file in the current working directory, you would add the string <code>plugins/shout</code> to the <code>plugins</code> array in your JSDoc configuration file:</p>
<p>JSDoc 3's plugin system offers extensive control over the parsing process. A plugin can affect the parse results by doing any of the following:</p>
<li>Defining a visitor for abstract syntax tree nodes</li>
71
70
</ul>
72
71
<h3id="event-handlers">Event Handlers</h3>
73
-
<p>At the highest level, a plugin may register handlers for specific named-events that occur in the documentation generation process. JSDoc will pass the handler
74
-
an event object containing pertinent information. Your plugin module should export a <code>handlers</code> object that contains your handler, like so:
75
-
</p>
72
+
<p>At the highest level, a plugin may register handlers for specific named events that JSDoc fires. JSDoc will pass an event object to the handler. Your plugin
73
+
module should export a <code>handlers</code> object that contains your handler, like so:</p>
<p>On Node.js, JSDoc fires events in the same order as the underlying code. On Mozilla Rhino, JSDoc fires all of the <code>jsdocCommentFound</code> events at once
85
83
as soon as it starts parsing a file; all other events are fired in the same order as the underlying code.</p>
84
+
<p>An event-handler plugin can stop later plugins from running by setting a <code>stopPropagation</code> property on the event object (<code>e.stopPropagation = true</code>).
85
+
A plugin can stop the event from firing by setting a <code>preventDefault</code> property (<code>e.preventDefault = true</code>).</p>
86
86
<h4id="event-parsebegin">Event: parseBegin</h4>
87
87
<p>The <code>parseBegin</code> event is fired before JSDoc starts loading and parsing the source files. Your plugin can control which files JSDoc will parse by
<p>At the lowest level, plugin authors can process each node in the abstract syntax tree (AST) by defining a node visitor that will visit each node, creating an
267
-
opportunity to do things like modify comments and trigger parser events for any arbitrary piece of code.</p>
268
-
<p>Plugins can define a node visitor by exporting a <code>nodeVisitor</code> object that contains a <code>visitNode</code> function, like so:</p>
266
+
<p>At the lowest level, plugin authors can process each node in the abstract syntax tree (AST) by defining a node visitor that will visit each node. By using a
267
+
node-visitor plugin, you can modify comments and trigger parser events for any arbitrary piece of code.</p>
268
+
<p>Plugins can define a node visitor by exporting an <code>astNodeVisitor</code> object that contains a
<p>The function is called on each node with the following parameters:</p>
278
279
<ul>
279
-
<li><code>node</code>: The AST node.</li>
280
+
<li><code>node</code>: The AST node. AST nodes are JavaScript objects that use the format defined by the Mozilla Parser API. You can use <ahref="http://esprima.org/demo/parse.html">Esprima's parser demo</a> to see the AST that will be created for your source code.</li>
280
281
<li><code>e</code>: The event. If the node is one that the parser handles, the event object will already be populated with the same things described in the <code>symbolFound</code> event above. Otherwise, it will be an empty object on which to set various properties.</li>
281
282
<li><code>parser</code>: The JSDoc parser instance.</li>
282
283
<li><code>currentSourceName</code>: The name of the file being parsed.</li>
283
284
</ul>
285
+
<p>If you run JSDoc on Mozilla Rhino, you can also export a <code>nodeVisitor</code> object that contains a
286
+
<code>visitNode</code> function. The <code>visitNode</code> function receives the same parameters as for <code>astNodeVisitor</code> objects, but the <code>node</code> parameter is a Rhino AST node, which is a Java object, rather than an Esprima-style JavaScript object. Rhino node visitors are deprecated as of JSDoc 3.3.0,
287
+
and support will be removed in a future version of JSDoc.</p>
284
288
<h4id="making-things-happen">Making things happen</h4>
285
289
<p>The primary reasons to implement a node visitor are to be able to document things that aren't normally documented (like function calls that create classes)
286
290
or to auto generate documentation for code that isn't documented. For instance, a plugin might look for calls to a <code>_trigger</code> method since it
287
291
knows that means an event is fired and then generate documentation for the event.</p>
288
292
<p>To make things happen, the <code>visitNode</code> function should modify properties of the event parameter. In general the goal is to construct a comment and
289
293
then get an event to fire. After the parser lets all of the node visitors have a look at the node, it looks to see if the event object has a <code>comment</code> property and an <code>event</code> property. If it has both, the event named in the event property is fired. The event is usually <code>symbolFound</code> or <code>jsdocCommentFound</code>, but theoretically, a plugin could define its own events and handle them.</p>
290
-
<h4id="example-of-a-node-visitor">Example of a node visitor</h4>
291
-
<p>Below is an example of what a plugin for documenting jQuery UI widgets might do. jQuery UI uses a factory function call to create widget classes. The plugin
292
-
looks for that function call and creates a symbol with documentation. It also looks for any <code>this._trigger</code> function calls and automatically creates
293
-
documentation for the events that are triggered:</p>
left = target && target.left && String(target.left.toSource()),
345
-
right = target && target.right && String(target.right.toSource());
346
-
return (left === "this" && right === "_trigger");
347
-
}
348
-
349
-
function isInWidgetFactory(node, depth) {
350
-
var parent = node.parent,
351
-
d = 0;
352
-
while (parent && (!depth || d < depth)) {
353
-
if (parent.type === Token.CALL) {
354
-
var target = parent.getTarget(),
355
-
left = target && target.left && String(target.left.toSource()),
356
-
right = target && target.right && String(target.right.toSource());
357
-
return ((left === "$" || left === "jQuery") && right === "widget");
358
-
} else {
359
-
parent = parent.parent;
360
-
d++;
361
-
}
362
-
}
363
-
return false;
364
-
}
365
-
</code></pre>
366
-
</figure>
367
-
<p>You'll notice a <code>finishers</code> property set. The finishers property should contain an array of functions to be called after the event is fired and
368
-
all the handlers have processed it. The parser provides an <code>addDocletRef</code> function that adds the doclet to the map (keyed off of the id property)
369
-
of doclets it knows about.</p>
370
-
<p>Lastly, the visitors are executed in the order the plugins are listed in the conf.json file. A plugin can stop later plugins from visiting a node by setting
371
-
a <code>stopPropagation</code> property on the event object (<code>e.stopPropagation = true</code>). A plugin can stop the event from firing by setting a
372
-
<code>preventDefault</code> property.</p>
373
-
<h3id="reporting-errors">Reporting Errors</h3>
294
+
<p>As with event-handler plugins, a node-visitor plugin can stop later plugins from running by setting a <code>stopPropagation</code> property on the event object
295
+
(<code>e.stopPropagation = true</code>). A plugin can stop the event from firing by setting a <code>preventDefault</code> property (<code>e.preventDefault = true</code>).</p>
296
+
<h2id="reporting-errors">Reporting Errors</h2>
374
297
<p>If your plugin needs to report an error, use one of the following methods in the <code>jsdoc/util/logger</code> module:
0 commit comments