How to Add and Use New JSDoc Tag Using Plugin?

Category: JavascriptTags: ,

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 &amp;&amp; methods.length &amp;&amp; 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.

Share

0 comments

Your email address will not be published. Required fields are marked *