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

Question

Я использую 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 более специфичные для данного приложения на основе Метеор. @where можно увидеть как-то вроде devdocs.io.

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

Answer 1

Да, в JSDoc можно добавить пользовательские теги. Вам нужно будет создать яваскрипт файл, который определяет свои метки вы хотите добавить:

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