Plant Documentation with JSDoc

Question

To avoid using new in my JavaScript code, I write factories to create objects.

I have tried many combinations, and the one that gives me the most satisfactory result is the following:

 /** * Document module * @module app/document */ (function () { 'use strict'; /** * Factory that creates a document object. * @alias module:app/document.factory * @return {document} */ function document() { /** * Get document id * @method id * @return {String} */ var id = function id() {...}, api = { id: id }; return api; } /** * This module exports the {@link module:app/document.factory|factory} function. */ module.exports = document; }()); 

The problem with these comments is the lack of a document object. Therefore, I cannot reference this object in another object, and I cannot inherit its documentation when I extend this object.

How can such an object be documented?

If I use the @typedef tag, I get a static factory method and the document object is correctly documented but the JSDoc does not generate id method documentation:

 /** * Document module. * @module app/document */ (function () { 'use strict'; /** * Factory that creates a document object. * @function module:app/document.factory * @return {document} */ function factory(agent) { /** * @callback document~id * @returns {String} */ var id = function id() {...}, /** * @typedef document * @property {document~id} id */ document = { id: id }; return document; } module.exports = factory; }()); 

Answer 1

My recommendation to you is to correctly determine the export of your module using @typedef to determine the type and then annotate the module.exports = factory file with @type {FactoryDefinition}

  /** @typedef {{ id: !string }} */ var DocumentDefinition; /** @typedef {!function(!object):!DocumentDefinition} */ var FactoryDefinition; /** @type {FactoryDefinition} */ module.exports = factory