create custom tags with jsdoc

Question

I am trying to create custom tags in jsdoc 3.4.2. The config.json file is

{
    \"tags\": {
        \"allowUnknownTags\": true,
        \"diction         


        

Answer 1

You are correct there is a two step process.

• First you define a tag for jsdoc to find in the code and update its doclet object (like you have done)
• Second you need the template, the thing which turns the doclet object into HTML, to know about the new property and do something with it.

Like you I've had a hard time finding instructions on making templates. The best I can suggest is check the jsdoc source code. You'll need to create a JavaScript file which exposes a publish function. The publish function will then iterate over the doclet object to generate HTML.

I had the same need as you but all I wanted to do was add a new section (header and text maybe a table of parameters) to the existing jsdoc template. I didn't really want to go and create a whole new template just for that so I ended up defining my tags in a way that they would end up appending or prepending HTML to the doclet.description property. Worked for me.

exports.defineTags = function(dictionary) {
    dictionary.defineTag('routeparam', {
        mustHaveValue: true,
        mustNotHaveDescription: false,
        canHaveType: true,
        canHaveName: true,
        onTagged: function(doclet, tag) {
            if (!doclet.routeparams) {
              doclet.routeparams = [];
            }

            doclet.routeparams.push({
              'name': tag.value.name,
              'type': tag.value.type ? (tag.value.type.names.length === 1 ? tag.value.type.names[0] : tag.value.type.names) : '',
              'description': tag.value.description || '',
            });
        }
    });
};

exports.handlers = {
  newDoclet: function(e) {
    const parameters = e.doclet.routeparams;
    if (parameters) {
      const table = tableBuilder.build('Route Parameters', parameters);

      e.doclet.description = `${e.doclet.description}
                              ${table}`;
    }
  }
}

Feel free to check out my repo to see how I did it https://github.com/bvanderlaan/jsdoc-route-plugin