@type for "exported modules" from node.js and good documentation descriptions?

Question

I am trying to be a good citizen and document my node modules .... but I am unsure of what to put in @type. I am using webstorm so it automatically puts @type {exports} but I am a little confused what i should place there?

Anyone give me a hand ? Here is a small module i am developing, removed code to emphasize the problem better. I am confused of what @type i should be using and how to document exports and requires with a good description.

Is @type {exports} a valid tag??

Anyone know a good standard or give there opion / what they would use / or are using

/**
 * 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

Keep in mind that you don't need to document every symbol in your source file. For example, there's probably no need to add a comment to the line where you import the winston module.

If you want users to know that getLogger() returns an instance of winston.Logger, you could use JSDoc's @external tag to document winston.Logger within your own code. Here's an incomplete but working example of how I would do it:

/**
 * 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;

If you want to treat winston as an implementation detail, you could use the @typedef tag to describe the object returned by getLogger(), without actually saying that it's a winston.Logger instance.

I don't use WebStorm, so I can't say which of these tags are supported in WebStorm. All of them will work in JSDoc 3.