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


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 ve algo como 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!


32
2017-11-09 21:24


origen


Respuestas:


Puedes usar @namespace con @name y @lends como este:

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

3
2017-11-09 21:58



No puede documentar funciones anidadas directamente. Pero puedes 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 configurando checkString como privado y interior ser descriptivo (ya que las funciones anidadas no se pueden describir), y luego paso -p para documentar funciones privadas. Finalmente, agrego un enlace a la función principal para referencia.

creo 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 controlo mis namepaths y depuro usando --explain bandera.


3
2017-12-17 02:11