create custom tags with jsdoc

问题

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.

回答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

来源：https://stackoverflow.com/questions/40263846/create-custom-tags-with-jsdoc

标签

javascript

jsdoc3