Comment puis-je JSDoc Un Objet Imbriqué Méthodes?

J'ai essayé d'utiliser JSDoc3 pour générer la documentation sur un fichier, mais je vais avoir quelques difficultés. Le fichier (qui est un Require.js module) est à peu près comme ceci:

define([], function() {

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

    return foo;
}

Le problème est, je ne peux pas obtenir baz à apparaître dans la documentation générée. Au lieu de cela, j'ai juste un fichier de la documentation pour un foo/foo module, qui énumère un bar membre, mais bar n'a pas de baz (juste un lien vers foocode source).

J'ai essayé de changer bardirective de @property au lieu de cela, et j'ai essayé de changer bazdirective de @member ou @property, mais aucun de cette aide. Peu importe ce que je fais, baz ne semble pas vouloir se montrer.

Personne ne sait ce que la directive de la structure que je pourrais utiliser pour obtenir baz apparaissent dans la documentation générée?

P. S. j'ai essayé de lire des pages comme celle-ci sur le JSDoc site http://usejsdoc.org/howto-commonjs-modules.html, mais elle ne décrit que des cas de foo.bar, pas foo.bar.baz.

InformationsquelleAutor machineghost | 2013-10-07

Vous pouvez utiliser une combinaison de @module ou @namespace avec @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;
});

MODIFIER que par Commentaire: (page Unique solution pour le module)

bar4 sans cette horrible tableau de propriété. ie @bien retiré 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;
});

Références -

*Note je n'ai pas essayé moi-même. S'il vous plaît essayer et de partager les résultats.

Merci, mais ça ne marche pas à tous. Je me retrouve avec un foo page de documentation avec rien (aucune mention de la barre), et un "global" de la barre de page avec pas de baz méthode 🙁
En fait, si j'utilise votre code littéralement, je n'ai même pas que: je viens d'obtenir un foo page avec rien sur elle. Mais si je fais quelque chose de semblable à ce que vous l'avez suggéré, avec mon code, j'obtiens l'équivalent d'une page foo avec rien et le "global" de la barre de page avec rien (c'est à dire. pas de baz).
je n'ai jamais voulu que vous avez à suivre mon exemple litéralement. j'ai simplement dit d'essayer de les utiliser. de toute façon. je l'ai fait. je suis en train de monter deux façons de bar, les deux ont des effets différents.
j'ai fini par l'adjonction de quatre bars. il existe de nombreuses façons de documenter les objets internes. S'il vous plaît essayer et de le commenter. je peux expliquer plus sur des approches spécifiques. vous pouvez exécuter jsdoc sur le code ci-dessus directement.
Il a travaillé ... ou au moins, il a travaillé un diable de beaucoup mieux! Le @namespace foo.bar semble avoir été la pièce manquante que j'avais besoin. La seule chose qui est encore moins que l'idéal est que chaque sous-niveau (par exemple. bar, bar2) obtient sa propre page. Idéalement, au lieu je voudrais voir bar et bar2 apparaissent sur foo's page (que je suis en train de générer une page de documentation du module foo, n'est pas un tas de pages pour chaque élément de foo) ... est-il possible de faire cela?
jetez un oeil à la bar4 de l'échantillon. il s'agira de mettre l'objet en tant que membre dans la foo. et bar4.baz4 en bas le long de avec d'autres méthodes. De cette façon, vous pouvez le détail de biens au sein de la même page de n'importe quel nid de niveau.
Parfait, j'ai reçu, vous le bounty, comme vous l'avez certainement bien mérité! Merci beaucoup pour l'aide.
heureux de vous aider. j'ai beaucoup appris moi-même.
Pour ceux ici en utilisant JSDoc3 avec ES6 classes, j'ai fourni un exemple dans ma réponse ci-dessous. Bonne chasse!
Votre deuxième édition, il est presque parfait. Il suffit de supprimer l'inutile @method tag memberof! foo# s'en charge déjà.

InformationsquelleAutor Mohit

7

Voici une façon simple de le faire:
```
/**
 * @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;
});
```
Noter que jsdoc peut en déduire les types baz4.baz4 et test sans avoir à dire @méthode et @membre.

Avoir eu jsdoc3 mettre de la documentation pour les classes et espaces de noms sur le même page que le module qui les définit, je ne sais pas comment le faire.

J'ai été en utilisant jsdoc3 pendant des mois, la documentation d'un petite bibliothèque et un grande application avec elle. Je préfère plier à jsdoc3 dans certains domaines que d'avoir à taper des tonnes de @-directives pour la plier à ma volonté.
- J'aime cela... mais la seule chose que jamais apparaît sur la droite de la navigation (en supposant que le modèle par défaut) est le foo. Souhaite que je pourrais avoir la brièveté de cette notation, plus un contenu complet!
InformationsquelleAutor Louis
0

Vous ne pouvez pas le document de fonctions imbriquées directement. Je n'aime pas les Griffes de solution, j'ai donc utilisé une autre application sans espaces de noms (c'est du JS, pas Java!).

Mise à jour:

J'ai mis à jour ma réponse à refléter l'exacte cas d'utilisation donné par les OP (ce qui est juste, puisque JSdoc est assez pénible à utiliser). Voici comment il devrait fonctionner:
```
/** @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;
}
```
Malheureusement JSdoc est un port de Java, donc il a beaucoup de caractéristiques qui font sens pour Java, mais pas pour le JS, et vice-versa. Par exemple, depuis en JS fonctions sont des objets de première classe, ils peuvent être traités comme des objets ou des fonctions. Donc faire quelque chose comme cela devrait fonctionner:
```
/** @function */
function hello() {
  /** @member {Object} */
  var hi = {};
}
```
Mais il n'est pas, parce que JSdoc qu'il reconnaît comme une fonction. Vous devez utiliser des espaces de noms, ma technique avec @link, ou d'en faire une classe:
```
/** @class */
function Hello() {
  /** @member {Object} */
  var hi = {};
}
```
Mais alors qui n'a pas de sens. N'classes existent en JS? pas, ils n'en ont pas.

Je pense que nous avons vraiment besoin de trouver une meilleure documentation de la solution. J'ai même vu des incohérences dans la documentation avec la façon dont les types doivent être affichés (par exemple {object} vs {Object}).

Vous pouvez également utiliser ma technique de document fermetures.
- S'il vous plaît mettre votre code dans la question, au lieu de le lier. Aussi, il serait utile si vous pouviez adapter pour les OP imbriquée foo bar baz objet littéral.
- Les espaces de noms sont universel de programmation concept. Toute langue peut être plus ou moins explicite à ce sujet, mais même dans des langues comme des JS qui ne sont pas explicites dans leur utilisation, ils sont encore très pertinent. Après tout, sinon pourquoi auraient-JSDoc, un standard de documentation purement pour le langage JavaScript (pas de Java) inclure une telle balise?
- JS n'a pas vraiment d'avoir des espaces de noms. Il n'a que deux périmètres: la portée mondiale et la portée de la fonction. Ce qui fait un espace de noms pour JS ressembler? Il est là parce que c'est un port de l'île de Java. JSdoc ne supporte pas beaucoup de bon JS idiomes directement, comme documenter JSON propriétés, des fermetures, des fonctions imbriquées, etc.
InformationsquelleAutor risto

Seulement pour améliorer le sur les Broches de la réponse un peu pour JSDoc3, je n'ai pu le faire fonctionner lorsque j'ai utilisé la @instance annotation au lieu de @membre.

ES6 exemple de code suivant:

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);
            },


            ...
        }
    }
}

InformationsquelleAutor Xunnamius

Vous devez vous connecter pour publier un commentaire.