I am working with JSDoc 3.6.4 to document JavaScript library. I want to mark certain functions available for Pro version so I want to add a new JSDoc tag “@pro” to indicate a certain feature available in Pro version.
This requires creating a new JSDoc plugin “protag”. Create a file “protag.js” and place it under JSDOC_ROOT\plugins\ folder with following content.
/**
@overview adds a tag @pro to any object
@module plugins/protag
@author Vishal Monpara
*/
'use strict';
exports.defineTags = function(dictionary) {
dictionary.defineTag("pro", {
mustHaveValue: false,
canHaveType: false,
canHaveName: false,
onTagged: function(doclet, tag) {
doclet.pro = true;
}
});
};
This plugin makes “.pro” property available for doclet. Refer to defineTag documentation for more information.
It requires a custom JSDoc Config with “allowUnknownTags”: true.
You may use this additional property by creating a new template “pro.tmpl” with following content.
<?js
var data = obj;
var self = this;
?>
<?js if (data.pro) { ?>
<span class="pro">PRO Version Only</span>
<?js } ?>
Now you can customize “container.tmpl” by calling above template as per your need. Here is a partial “container.tmpl” code
.....
.....
.....
<h3 class="subsection-title">Summary</h3>
<table class="params">
<thead>
<tr>
<th class="last">Constructor</th>
</tr>
</thead>
<tbody>
<tr>
<td><?js= doc.attribs + 'new ' + doc.name + (doc.signature || '') ?><?js= self.partial('pro.tmpl', doc) ?></td>
</tr>
</tbody>
</table>
<?js
}
// for methods/functions
var methods = self.find({kind: 'function', memberof: isGlobalPage ? {isUndefined: true} : doc.longname});
if (methods && methods.length && methods.forEach) {
?>
<br />
<table class="params">
<thead>
<tr>
<th class="last">Method Summary</th>
</tr>
</thead>
<tbody>
<?js methods.forEach(function(m) { ?>
<tr>
<td><?js= m.attribs + '<a href="#' + m.name + '">' + m.name + '</a>' + (m.signature || '') ?><?js= self.partial('pro.tmpl', m) ?><br />
<?js= m.description ?>
</td>
</tr>
<?js }); ?>
</tbody>
</table>
<?js
}
?>
.....
.....
.....
For more information on customizing JSDoc output file, refer to Customize JSDoc documentation file tutorial.