javascript - comment - ¿Cómo hago los métodos de JSDoc A Objeto anidado?

jsdoc return

Question

He estado tratando de usar JSDoc3 para generar documentación en un archivo, pero estoy teniendo algunas dificultades. El archivo (que es un módulo Require.js) básicamente se ve así:

define([], function() {

    /*
     * @exports mystuff/foo
     */
    var foo = {
        /**
         * @member
         */
        bar: {
            /**
             * @method
             */
            baz: function() { /*...*/ }
        }
    };

    return foo;
}

El problema es que no puedo hacer que baz aparezca en la documentación generada. En cambio, acabo de obtener un archivo de documentación para un módulo foo/foo , que enumera un miembro de la bar , pero la bar no tiene baz (solo un enlace al código fuente de foo ).

Intenté cambiar la directiva de @property a @property , y he intentado cambiar la directiva de @member a @member o @property , pero nada de eso me ayuda. No importa lo que haga, Baz simplemente no parece querer aparecer.

¿Alguien sabe qué estructura directiva podría usar para que Baz aparezca en la documentación generada?

PD. He intentado leer páginas como esta en el sitio de JSDoc http://usejsdoc.org/howto-commonjs-modules.html , pero solo describe casos de foo.bar , no de foo.bar.baz .

Answer 1

Aquí hay una manera simple de hacerlo:

/**
 * @module mystuff/foo
 * @version 1.0
 */
define([], function() {

/** @lends module:mystuff/foo */
var foo = {
    /**
     * A method in first level, just for test
     */
    testFirstLvl: function(msg) {},
    /**
     * @namespace
     */
    bar4: {
        /**
         * This is the description for baz4.
         */
        baz4: function() { /*...*/ },
        /**
         * This is the description for test.
         */
        test : true
    }
};

return foo;
});

Tenga en cuenta que jsdoc puede inferir los tipos baz4.baz4 y test sin tener que decir @method y @member.

En cuanto a que jsdoc3 ponga la documentación para clases y espacios de nombres en la misma página que el módulo que los define, no sé cómo hacerlo.

He estado usando jsdoc3 durante meses, documentando una pequeña biblioteca y una gran aplicación con ella. Prefiero plegarme a la voluntad de jsdoc3 en algunas áreas que tener que escribir resmas de @ -directivas para doblarlo a mi voluntad.

Answer 2

No puede documentar funciones anidadas directamente. No me gustaba la solución Prongs, así que utilicé una implementación diferente sin espacios de nombres (¡es JS, no Java!).

Actualizar:

Actualicé mi respuesta para reflejar el caso de uso exacto dado por el OP (que es justo, ya que JSdoc es bastante doloroso de usar). Así es como funcionaría:

/** @module foobar */

/** @function */
function foobarbaz() {
    /* 
     * You can''t document properties inside a function as members, like you
     * can for classes. In Javascript, functions are first-class objects. The
     * workaround is to make it a @memberof it''s closest parent (the module).
     * manually linking it to the function using (see: {@link ...}), and giving
     * it a @name.
     */

    /**
     * Foo object (see: {@link module:foobar~foobarbaz})
     * @name foo
     * @inner
     * @private
     * @memberof module:foobar
     * @property {Object} foo - The foo object
     * @property {Object} foo.bar - The bar object
     * @property {function} foo.bar.baz - The baz function
     */
    var foo = {

        /* 
         * You can follow the same steps that was done for foo, with bar. Or if the
         * @property description of foo.bar is enough, leave this alone. 
         */
        bar: {

            /*
             * Like the limitation with the foo object, you can only document members 
             * of @classes. Here I used the same technique as foo, except with baz.
             */

            /**
             * Baz function (see: {@link module:foobar~foo})
             * @function
             * @memberof module:foobar
             * @returns {string} Some string
             */
            baz: function() { /*...*/ }
        }
    };

    return foo;
}

Lamentablemente, JSdoc es un puerto de Java, por lo que tiene muchas características que tienen sentido para Java pero no para JS, y viceversa. Por ejemplo, dado que en JS las funciones son objetos de primera clase, se pueden tratar como objetos o funciones. Entonces, hacer algo como esto debería funcionar:

/** @function */
function hello() {
  /** @member {Object} */
  var hi = {};
}

Pero no lo hará, porque JSdoc lo reconoce como una función. Tendría que usar espacios de nombres, mi técnica con @link , o hacer una clase:

/** @class */
function Hello() {
  /** @member {Object} */
  var hi = {};
}

Pero eso tampoco tiene sentido. ¿Existen clases en JS? no , no lo hacen

Creo que realmente necesitamos encontrar una mejor solución de documentación. Incluso he visto incoherencias en la documentación con respecto a cómo deben mostrarse los tipos (por ejemplo, {object} vs {Object} ).

También puedes usar mi técnica para documentar closures .

Answer 3

Puede usar una combinación de http://usejsdoc.org/howto-commonjs-modules.html o @namespace junto con @memberof .

define([], function() {

    /**
     * A test module foo
     * @version 1.0
     * @exports mystuff/foo
     * @namespace foo
     */
    var foo = {
        /**
         * A method in first level, just for test
         * @memberof foo
         * @method testFirstLvl
         */
        testFirstLvl: function(msg) {},
        /**
         * Test child object with child namespace
         * @memberof foo
         * @type {object}
         * @namespace foo.bar
         */
        bar: {
            /**
             * A Test Inner method in child namespace
             * @memberof foo.bar
             * @method baz
             */
            baz: function() { /*...*/ }
        },
        /**
         * Test child object without namespace
         * @memberof foo
         * @type {object}
         * @property {method} baz2 A child method as property defination
         */
        bar2: {
            /**
             * A Test Inner method
             * @memberof foo.bar2
             * @method baz2
             */
            baz2: function() { /*...*/ }
        },
        /**
         * Test child object with namespace and property def.
         * @memberof foo
         * @type {object}
         * @namespace foo.bar3
         * @property {method} baz3 A child method as property defination
         */
        bar3: {
            /**
             * A Test Inner method in child namespace
             * @memberof foo.bar3
             * @method baz3
             */
            baz3: function() { /*...*/ }
        },
        /**
         * Test child object
         * @memberof foo
         * @type {object}
         * @property {method} baz4 A child method
         */
        bar4: {
             /**
             * The @alias and @memberof! tags force JSDoc to document the
             * property as `bar4.baz4` (rather than `baz4`) and to be a member of
             * `Data#`. You can link to the property as {@link foo#bar4.baz4}.
             * @alias bar4.baz4
             * @memberof! foo#
             * @method bar4.baz4
             */
            baz4: function() { /*...*/ }
        }
    };

    return foo;
});

EDITAR según el comentario: (solución de página única para el módulo)

bar4 sin esa fea tabla de propiedades. es decir @property eliminado de bar4.

define([], function() {

    /**
     * A test module foo
     * @version 1.0
     * @exports mystuff/foo
     * @namespace foo
     */
    var foo = {
        /**
         * A method in first level, just for test
         * @memberof foo
         * @method testFirstLvl
         */
        testFirstLvl: function(msg) {},
        /**
         * Test child object
         * @memberof foo
         * @type {object}
         */
        bar4: {
             /**
             * The @alias and @memberof! tags force JSDoc to document the
             * property as `bar4.baz4` (rather than `baz4`) and to be a member of
             * `Data#`. You can link to the property as {@link foo#bar4.baz4}.
             * @alias bar4.baz4
             * @memberof! foo#
             * @method bar4.baz4
             */
            baz4: function() { /*...*/ },
            /**
             * @memberof! for a memeber
             * @alias bar4.test
             * @memberof! foo#
             * @member bar4.test
             */
             test : true
        }
    };

    return foo;
});

Referencias

1. Otra pregunta sobre espacios de nombres anidados
2. Para una forma alternativa de usar Namespaces
3. Documentar objetos literales

* Tenga en cuenta que no lo he probado yo mismo. Por favor, intente y comparta los resultados.

Answer 4

Solo para mejorar la respuesta de Prongs un poco para JSDoc3 , solo pude hacer que funcionara cuando utilicé la anotación @instance en lugar de @member .

El código de ejemplo ES6 sigue:

class Test
{
    /**
     * @param {object} something
     */
    constructor(something)
    {
        this.somethingElse = something;

        /**
         * This sub-object contains all sub-class functionality.
         *
         * @type {object}
         */
        this.topology = {
            /**
             * Informative comment here!
             *
             * @alias topology.toJSON
             * @memberof! Test#
             * @instance topology.toJSON
             * 
             * @returns {object} JSON object
             */
            toJSON()
            {
                return deepclone(privatesMap.get(this).innerJSON);
            },


            ...
        }
    }
}