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

我正在努力成为一个好公民，并logging我的节点模块….但我不确定要在@type中放置什么。 我正在使用webstorm所以它会自动把@type {出口}，但我有点困惑，我应该放在那里？

任何人都帮我一把吗？ 这里是我正在开发的一个小模块，删除代码以更好地强调问题。 我很困惑我应该使用什么types，以及如何logging出口，并需要一个很好的描述。

是@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

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

如果您希望用户知道getLogger()返回getLogger()的实例， winston.Logger可以使用JSDoc的@external标记在您自己的代码中loggingwinston.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} 

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