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

【问题标题】：@type for "exported modules" from node.js and good documentation descriptions?@type 来自 node.js 的“导出模块”和良好的文档描述？
【发布时间】：2014-08-05 04:12:29
【问题描述】：

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

【解决方案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 中工作。

【讨论】：

谢谢。这帮助很大。

【解决方案2】：

@type {exports}

绝对是错误的。 docs 建议使用 @module 来记录 CommonJS 模块。另见module tag definition 但它们并不太有用/不完整。此外，WebStorm 还不支持 @module 和 @exports 标签 - 请参阅 WEB-11493 一些提示建议在http://blog.jetbrains.com/webstorm/2014/03/webstorm-8-rc/#comment-21822

【讨论】：