Cómo documentar funciones anónimas (cierre) con jsdoc-toolkit

Question

Estoy intentando documentar mi código usando JSDoc-toolkit. Mi código comienza envolviéndolo con una función anónima autoejecutable. ¿Cómo en el mundo documenté esto? He pasado casi todo el día en esto. JS Docs no reconocerá nada dentro del cierre de la función anónima debido a que no sabe qué hacer con él. Se rompe y ninguno de mis comentarios aparece.

Mi código se parece a esto.

/** 
* @fileoverview BLA BLA BLA 
*/ 

/** 
* This is where I don't know what to put. 
*/ 
(function() { 
    "use strict"; 

    /** or here */ 
    var stlib = function (param, param, param) { 
     /** or here */ 
     var share = { 
      /** or here */ 
      config: { 
       button: DOM Element, 
       property: blablabla 
      }, 

      init: function() { ...some init code here} 
     }; 

     share.init(); 
    }; 

    widgets.add("share", stlib); 
}()); 

¡Gracias!

Answer 1

Puede utilizar @namespace con @Name y @lends así:

/** 
* @name MyNamespace 
* @namespace Hold all functionality 
*/ 
(function() { 
    "use strict"; 
    /** @lends MyNamespace*/ 
    var stlib = function (param, param, param) { ...All of my code...}; 
}()); 

Answer 2

No se puede documentar funciones anidadas directamente. Pero se puede hacer algo como esto:

/** 
* @module foobar 
*/ 

/** 
* @function 
* @author Baa 
* @name hello 
* @description Output a greeting 
* @param {String} name - The name of the person to say hello 
*/ 
(function hello(name) { 
    /** 
    * @function 
    * @author Baz 
    * @inner 
    * @private 
    * @memberof module:foobar 
    * @description Check if the argument is a string (see: {@link module:foobar~hello}) 
    * @param {String} string - The string 
    * @returns {String} Returns true if string is valid, false otherwise 
    */ 
    var isString = function checkString(string) { return typeof string === 'string'; }; 
    if (isString(name)) 
     console.log('Hello ' + name + '!'); 
}('Mr. Bubbles')); 

Aquí estoy fijando checkString como privada y interior a ser descriptiva (ya que las funciones anidadas no se pueden describir), y luego pasar a -p documentar funciones privadas. Finalmente, agrego un enlace a la función principal para referencia.

Creo que jsdoc es innecesariamente quisquilloso y necesita ser reemplazado por algo mejor. Es un puerto de javadoc, por lo que tiene muchas cosas que son relevantes para Java pero no para JS, y viceversa. Hay expresiones idiomáticas JS muy comunes, como cierres o funciones anidadas, que son difíciles o imposibles de documentar.

Siempre compruebo mi namepaths y depuro usando la bandera --explain.