Как добавить теги в JSDoc?

Я использую 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
person corvid    schedule 27.07.2015    source источник

Ответы (1)


arrow_upward
3
arrow_downward

Да, в 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 для шаблонов по умолчанию, чтобы отображать вашу информацию в сгенерированных документах. Или вы можете создать свой собственный шаблон и определить свой собственный синтаксический анализ, чтобы добавить свои теги в сгенерированную документацию.

person Don Pavlik    schedule 26.11.2015