Dokumentowanie fabryk przy użyciu JSDoc

Question

Aby uniknąć używania new w moim kodzie JavaScript, piszę fabryki, aby tworzyć obiekty.

Próbowałem wielu kombinacji i jeden, który daje mi najbardziej zadowalający wynik jest następujący:

/** 
* 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; 
}()); 

Problem z tych uwag jest brak document obiekt zdefiniowany. Dlatego nie mogę odwoływać się do tego obiektu w innym obiekcie i nie mogę dziedziczyć jego dokumentacji, gdy rozszerzam ten obiekt.

Jaki jest właściwy sposób udokumentowania tego rodzaju obiektu?

Gdybym użyć tagu @typedef, mam statyczną factory metodę a obiekt document właściwie udokumentowany ale bez dokumentacji id metoda jest generowany przez JSDoc:

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

Moja rada dla ciebie jest, aby dobrze określić eksport do modułu za pomocą @typedef, aby zdefiniować typ, a następnie dodać adnotację do modułu .exports = fabrycznie z @type {FactoryDefinition}

/** @typedef {{ id: !string }} */ 
var DocumentDefinition; 

/** @typedef {!function(!object):!DocumentDefinition} */ 
var FactoryDefinition; 

/** @type {FactoryDefinition} */ 
module.exports = factory