How to Add and Use New JSDoc Tag Using Plugin?

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 that certain features available in Pro version.

How to Create a New JSDoc Tag?

If we want to have a new tag supported, you may easily extend JSDoc by creating a new JSDoc plugin called “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;
        }
    });
};

When JSDoc parses Javascript file and encounters “@pro” tag within documentation, this plugin makes “.pro” property available for doclet. Refer to defineTag documentation for more information.

It requires a custom JSDoc Config with "allowUnknownTags": true.

How to Use the New JSDoc Tag to Generate HTML?

Previous code would provide additional property called “.pro” to your doclet object. Please note that either this property is absent from the object or if set, it value is true. When you are conditionally generating HTML, you may want to handle undefined “pro” property as well as specific value. 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.