CODEWITHSUNDEEP
javascriptdocumentationdocumentation-generationjsdoc3
corvid
corvid

Reputation: 11187

How to add tags to JSDoc?

I am using Meteor which has some odd caveats compared to normal JavaScript. I want to add some tags in order to make the documentation more explicit.

Meteor.methods({
  /**
  * Upgrade a user's role
  *
  * @where Anywhere
  * @rolerequired 'admin'
  *
  * @module Meteor.methods
  * @method Roles.upgrade
  * @param {String|Object} user the userId or the user document to update
  * @param {String} role the role to add the user to
  * @throws Meteor.Error 401 if the user trying to upgrade was not authorized to do so
  * 
  * @example
  * Meteor.call('Roles.upgrade', Meteor.users.findOne(), function (err) {
    if (!err) {
      console.log('User successfully added to role');
    } else {
      Router.error(401);
    }
  })
  */
  'Roles.upgrade': function (user, role) {
    if (Roles.userIsInRole(this.userId, 'admin')) {
      return Roles.addUserToRoles(user, role);
    } else {
      throw new Meteor.Error(401, "Not authorized to upgrade roles")
    }
  }
});

The @where and @rolerequired are more specific to this Meteor based application. The @where can be seen in something like devdocs.io.

How to add tags to JSDoc?

Upvotes: 2

Views: 1956

Answers (1)

Don Pavlik
Don Pavlik

Reputation: 136

Yes, it is possible to add custom tags to JSDoc. You will need to create a javascript file that defines your tags you want to add:

custom_tags.js:

exports.defineTags = function(dictionary) {
  dictionary.defineTag('where', {
    mustHaveValue: true,
    onTagged : function(doclet, tag) {
      doclet.where = doclet.where || [];
      doclet.where.push(tag.value);
    }
  });
};

Then you will need to add the location to that javascript file to a conf.json which has your plugin listed as part of the path

conf.json:

{
  "plugins": [
    "plugins/test"
  ],
}

Finally, you will need to update a .tmpl file for the default templates to render your information in the generated documents. Or you can create your own template and define your own parse to add your tags to the generated documentation.

Upvotes: 4

Related Questions