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,
        "dictionaries": ["jsdoc","closure"]
    },

    "source": {
        "include": [
            "app/"
            ],
        "exclude": [],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [
        "plugins/custom-tags.js"
        ],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    },
    "opts": {
        "destination": "./docs",
        "recurse": true,
        "encoding": "utf8"
    }
}

In the custom-tags.js i have added these lines

exports.defineTags = function (dictionary) {
    dictionary.defineTag("service", {
        mustHaveValue: true,
        canHaveType: false,
        canHaveName: true,
        onTagged: function (doclet, tag) {
            doclet.service = tag.value;
        }
    });
}; 

But when i used the @service in the code, it is not showing. I had looked some link relating this and found out for custom tags we need to create template, but not found a way of creating one. I had installed jsdoc globally on my windows machine.

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