来自node.js的“导出模块”的@type和良好的文档描述？

Question

我想成为一个好公民并记录我的节点模块....但我不确定要放入什么样的@type。 我正在使用webstorm所以它自动放入@type {exports}但是我有点困惑我应该放在那里？

有人帮我一把吗？ 这是我正在开发的一个小模块，删除代码以更好地强调问题。 我很困惑@type i应该使用什么以及如何记录导出并需要良好的描述。

@type {exports}是一个有效的标签吗？

任何人都知道一个好的标准或给予opion /他们将使用/或正在使用的东西

/**
 * 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;

Answer 1

请记住，您不需要记录源文件中的每个符号。 例如，可能不需要在导入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中使用。

Answer 2

@type {exports}

绝对是错的。 文档建议使用@module来记录CommonJS模块。 另请参见模块标签定义但它们不太有用/完整..此外，WebStorm还不支持@module和@exports标签 - 请参阅WEB-11493 http://blog.jetbrains.com/webstorm上建议了一些提示/ 2014/03 / webstorm-8-RC /＃评论- 21822