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 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 {{1}} 1}}实例。

我没有使用WebStorm，所以我无法说出WebStorm中支持哪些标签。所有这些都可以在JSDoc 3中使用。

Answer 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

建议了一些提示

@type for＆＃34;导出模块＆＃34;来自node.js和良好的文档描述？

2 个答案: