@type для экспортированных модулей из node.js и хорошее описание документации?

Я пытаюсь быть хорошим гражданином и документировать свои модули узлов .... но я не уверен, что добавить в @type. Я использую webstorm, поэтому он автоматически помещает @type {exports}, но я немного запутался, что я должен туда поместить?

Кто-нибудь протянет мне руку? Вот небольшой модуль, который я разрабатываю, удаленный код, чтобы лучше подчеркнуть проблему. Я запутался в том, какой @type я должен использовать и как документировать экспорт и требует хорошего описания.

Является ли @type {exports} допустимым тегом??

Кто-нибудь знает хороший стандарт или дает там мнение / что они будут использовать / или используют

/**
 * A module for logging
 * @module logger
 * @type {exports}
 */


/**
 * HOW TO DOCUMENT THIS ???????????? GOOD DESCRIPTION??
 * @type {exports}
 */
var winston = require('winston');

/**
 * Returns an instance of the logger object
 * @param module
 * @returns {exports.Logger}
 */
function getLogger(module) {

    return new winston.Logger({
       ....
    });
}

/**
 * HOW TO DOCUMENT THIS ????????????  GOOD DESCRIPTION??
 * @type {getLogger}
 */
module.exports = getLogger;

node.js jsdoc webstorm jsdoc3
person Martin    schedule 14.06.2014    source источник

Ответы (2)


arrow_upward
3
arrow_downward

Имейте в виду, что вам не нужно документировать каждый символ в исходном файле. Например, возможно, нет необходимости добавлять комментарий к строке, где вы импортируете модуль winston.

Если вы хотите, чтобы пользователи знали, что getLogger() возвращает экземпляр winston.Logger, вы можете использовать тег JSDoc @external для документ winston.Logger в вашем собственном коде. Вот неполный, но работающий пример того, как я бы это сделал:

/**
 * A module for logging
 * @module logger
 * @type {exports}
 */

/**
 * The logging library used by this module.
 * @external winston
 */

/**
 * The logging class exposed by this module.
 * @name external:winston.Logger
 * @class
 */

/**
 * Method to log a message at a specified level.
 * @name external:winston.Logger#log
 * @function
 * @param {string} level - The log level to use.
 * @param {string} message - The message to log.
 */

var winston = require('winston');

/**
 * Returns an instance of the logger.
 * @alias module:logger.getLogger
 * @returns {external:winston.Logger} A logger instance.
 */
function getLogger() {

    return new winston.Logger({
       // ...
    });
}

module.exports = getLogger;

Если вы хотите рассматривать winston как деталь реализации, вы можете использовать тег @typedef для описания объекта. возвращено getLogger(), фактически не говоря, что это экземпляр winston.Logger.

Я не использую WebStorm, поэтому не могу сказать, какие из этих тегов поддерживаются в WebStorm. Все они будут работать в JSDoc 3.

person Jeff Williams    schedule 17.06.2014
comment
Спасибо. Это очень помогло. - person Martin; 23.06.2014

arrow_upward
1
arrow_downward 

@type {exports}

определенно неправильно. В документах предлагается использовать @module для документирования модулей CommonJS. См. также определение тега модуля. Но они не слишком полезны/полны. Более того, WebStorm не но поддерживают теги @module и @exports — см. WEB-11493. Некоторые подсказки предлагаются в http://blog.jetbrains.com/webstorm/2014/03/webstorm-8-rc/#comment-21822

person lena    schedule 17.06.2014