1

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

2 回答 2

3

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

于 2014-06-17T16:20:32.513 回答
1 
@type {exports}

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

于 2014-06-17T12:54:28.063 回答