如何给 JSDoc 添加标签？答案

【问题标题】：How to add tags to JSDoc?如何给 JSDoc 添加标签？
【发布时间】：2015-10-17 16:19:43
【问题描述】：

我正在使用 Meteor，与普通 JavaScript 相比，它有一些奇怪的警告。我想添加一些标签以使文档更明确。

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")
    }
  }
});

@where 和 @rolerequired 更具体地适用于这个基于 Meteor 的应用程序。 @where 可以在 devdocs.io 之类的文件中看到。

如何给JSDoc添加标签？

【问题讨论】：

标签： javascript documentation documentation-generation jsdoc3

【解决方案1】：

是的，可以将自定义标签添加到 JSDoc。您需要创建一个 javascript 文件来定义您要添加的标签：

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);
    }
  });
};

然后您需要将该 javascript 文件的位置添加到 conf.json 中，该文件将您的插件列为路径的一部分

conf.json:

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

最后，您需要更新默认模板的 .tmpl 文件，以在生成的文档中呈现您的信息。或者，您可以创建自己的模板并定义自己的解析以将标签添加到生成的文档中。

【讨论】：