382 votes

Comment décrire les arguments « objet » dans jsdoc ?

<pre><code></code><p>Mais comment puis-je décrire comment l’objet paramètres devrait être structurée ? Par exemple, il doit être quelque chose comme :</p><pre><code></code></pre></pre>

507voto

insin Points 19509

À partir de l' @param page wiki:


Les Paramètres Avec Des Propriétés

Si un paramètre est prévu d'avoir une propriété particulière, vous pouvez le document que, immédiatement après le @param balise pour ce paramètre, comme ceci:

 /**
  * @param userInfo Information about the user.
  * @param userInfo.name The name of the user.
  * @param userInfo.email The email of the user.
  */
 function logIn(userInfo) {
        doLogIn(userInfo.name, userInfo.email);
 }

Il y a @config de la balise qui a suivi immédiatement le correspondant @param, mais il semble avoir été déprécié (exemple ici).

141voto

vogdb Points 670

Je vois qu'il y a déjà eu une réponse sur le @de retour mais je veux vous donner plus de détails à ce sujet.

Tout d'abord l'officiel jsdoc 3 la documentation ne pas nous donner des exemples sur le @de retour de l'objet personnalisé. Veuillez voir http://usejsdoc.org/tags-returns.html. Voyons maintenant ce que nous pouvons faire jusqu'à un certain standard apparaît.

  • La fonction renvoie l'objet où les clés sont générées dynamiquement. Exemple: {1: 'Pete', 2: 'Mary', 3: 'John'}. Habituellement, nous itérer sur cet objet avec l'aide d' for(var key in obj){...} .

    Possible jsdoc selon http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JsTypes

    /**
     * @return {Object.<number, string>}
     */
    function getTmpObject() {
        var result = {}
        for (var i = 10; i >= 0; i--) {
            result[i * 3] = 'someValue' + i;
        }
        return result
    }
    
  • La fonction renvoie l'objet où les touches sont connus consts. Exemple: {id: 1, title: 'Bonjour le monde', type: 'APPRENDRE', les enfants: {...}}. On peut facilement accéder aux propriétés de cet objet, object.id.

    Possible jsdoc selon https://groups.google.com/forum/#!topic/jsdoc-utilisateurs/TMvUedK9tC4

    • Faux.

      /**
       * Generate a point.
       *
       * @returns {Object} point - The point generated by the factory.
       * @returns {number} point.x - The x coordinate.
       * @returns {number} point.y - The y coordinate.
       */
      var pointFactory = function (x, y) {
          return {
              x:x,
              y:y
          }
      }
      
    • The Full Monty.

      /**
       @class generatedPoint
       @private
       @type {Object}
       @property {number} x The x coordinate.
       @property {number} y The y coordinate.
       */
      function generatedPoint(x, y) {
          return {
              x:x,
              y:y
          };
      }
      
      /**
       * Generate a point.
       *
       * @returns {generatedPoint} The point generated by the factory.
       */
      
      var pointFactory = function (x, y) {
          return new generatedPoint(x, y);
      }
      
    • Définir un Type.

      /**
       @typedef generatedPoint
       @type {Object}
       @property {number} x The x coordinate.
       @property {number} y The y coordinate.
       */
      
      
      /**
       * Generate a point.
       *
       * @returns {generatedPoint} The point generated by the factory.
       */
      
      var pointFactory = function (x, y) {
          return {
              x:x,
              y:y
          }
      }
      

    Selon http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#JsTypes

    • Le Type D'Enregistrement.

      /**
       * @return {{myNum: number, myObject}}
       * An anonymous type with the given type members.
       */
      function getTmpObject() {
          return {
              myNum: 2,
              myObject: 0 || undefined || {}
          }
      }
      

21voto

maliboo Points 81

0voto

Mike DeSimone Points 20059

Il existe un nouveau tag @config pour ces cas. Ils sont liés aux @param précédents.

 /** My function does X and Y.
    @params {object} parameters An object containing the parameters
    @config {integer} setting1 A required setting.
    @config {string} [setting2] An optional setting.
    @params {MyClass~FuncCallback} callback The callback function
*/
function(parameters, callback) {
    // ...
};

/**
 * This callback is displayed as part of the MyClass class.
 * @callback MyClass~FuncCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */
 

Prograide.com

Prograide est une communauté de développeurs qui cherche à élargir la connaissance de la programmation au-delà de l'anglais.
Pour cela nous avons les plus grands doutes résolus en français et vous pouvez aussi poser vos propres questions ou résoudre celles des autres.

Powered by:

X