node.js - 来自node.js的@type for "exported modules"和良好的文档描述？

Question

我正在努力成为一个好公民并记录我的 Node 模块......但我不确定要在@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;

Answer 1

请记住，您不需要记录源文件中的每个符号。例如，可能不需要在导入 winston 模块的行添加注释。

如果您希望用户知道 getLogger() 返回 winston.Logger 的实例，您可以使用 JSDoc 的 @external tag在您自己的代码中记录 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 tag描述 getLogger() 返回的对象，而不实际说它是一个 winston.Logger 实例。

我不使用WebStorm，所以我不能说WebStorm支持这些标签中的哪些。所有这些都可以在 JSDoc 3 中工作。