JSDoc: structure de l'objet de retour

144

Comment puis-je informer JSDoc de la structure d'un objet renvoyé. J'ai trouvé la @return {{field1: type, field2: type, ...}} descriptionsyntaxe et l' ai essayé:

/**
 * Returns a coordinate from a given mouse or touch event
 * @param  {TouchEvent|MouseEvent|jQuery.Event} e    
 *         A valid mouse or touch event or a jQuery event wrapping such an
 *         event. 
 * @param  {string} [type="page"]
 *         A string representing the type of location that should be
 *         returned. Can be either "page", "client" or "screen".
 * @return {{x: Number, y: Number}} 
 *         The location of the event
 */
var getEventLocation = function(e, type) {
    ...

    return {x: xLocation, y: yLocation};
}

Bien que cette analyse réussisse, la documentation qui en résulte indique simplement:

Returns: 
    The location of an event
    Type: Object

Je développe une API et j'ai besoin que les gens sachent l'objet qu'ils recevront. Est-ce possible dans JSDoc? J'utilise JSDoc3.3.0-beta1.

javascript documentation-generation jsdoc code-documentation jsdoc3 Loup noir
la source
Je sais que @typedefc'est une solution de contournement / solution, mais il semble étrange que cela ne fonctionne pas avec des objets littéraux. Si quelqu'un tombe sur cela à l'avenir (comme je l'ai fait), j'ai ajouté un problème github.com/jsdoc/jsdoc/issues/1678 qui pourrait avoir plus d'informations que cette page.
Leszek

Réponses:

263

Définissez votre structure séparément à l' aide d'un @typdef :

/**
 * @typedef {Object} Point
 * @property {number} x - The X Coordinate
 * @property {number} y - The Y Coordinate
 */

Et utilisez-le comme type de retour:

/**
 * Returns a coordinate from a given mouse or touch event
 * @param  {TouchEvent|MouseEvent|jQuery.Event} e    
 *         A valid mouse or touch event or a jQuery event wrapping such an
 *         event. 
 * @param  {string} [type="page"]
 *         A string representing the type of location that should be
 *         returned. Can be either "page", "client" or "screen".
 * @return {Point} 
 *         The location of the event
 */
var getEventLocation = function(e, type) {
    ...

    return {x: xLocation, y: yLocation};
}
BGerrissen
la source
2
Merci. Plusieurs @returninstructions fonctionnent en effet, mais elles sont répertoriées dans la sortie comme s'il s'agissait de plusieurs retours (une puce indique point - Object, puis deux autres puces pour point.x - Numberet point.y - Number). Bien que je puisse vivre avec cela, je suppose qu'il n'y a aucun moyen d'avoir une sortie condensée de l'objet retourné? Ou du moins les entrées pour point.xet en point.yretrait?
BlackWolf
1
Oui, cela semble être la meilleure option. Je pensais qu'il pourrait y avoir un moyen d'avoir une entité de retour non nommée, mais l' @typedefapproche est la plus claire en termes de sortie de documentation, merci!
BlackWolf
groovy, supprimé la première option car la deuxième option est tout simplement la meilleure.
BGerrissen
1
Vous feriez mieux d'ajouter @innerou de type la définition aura une globalportée dans la documentation. +1
Onur Yıldırım
1
J'ai toujours utilisé @typedef {Object} Point. En fait, l'utilisation de ce formulaire à deux lignes met Pointen évidence dans PhpStorm avec le message "Variable non résolue ou type Point". La @typedefdocumentation prend en charge cela, mais je ne souhaite pas modifier cette réponse s'il s'agit d'une variante valide.
David Harkness
22

Une alternative aux suggestions déjà publiées, vous pouvez utiliser ce format:

/**
 * Get the connection state.
 *
 * @returns {Object} connection The connection state.
 * @returns {boolean} connection.isConnected Whether the authenticated user is currently connected.
 * @returns {boolean} connection.isPending Whether the authenticated user's connection is currently pending.
 * @returns {Object} connection.error The error object if an error occurred.
 * @returns {string} connection.error.message The error message.
 * @returns {string} connection.error.stack The stack trace of the error.
 */
getConnection () {
  return {
    isConnected: true,
    isPending: false,
    error
  }
}

qui donnera la sortie de documentation suivante:

    Get the connection state.

    getConnection(): Object

    Returns
    Object: connection The connection state.
    boolean: connection.isConnected Whether the authenticated user is currently connected.
    boolean: connection.isPending Whether the authenticated users connection is currently pending.
    Object: connection.error The error object if an error occurred.
    string: connection.error.message The error message.
    string: connection.error.stack The stack trace of the error.
Matt Pengelly
la source
17

Une solution propre consiste à écrire une classe et à la renvoyer.

/** 
 *  @class Point
 *  @type {Object}
 *  @property {number} x The X-coordinate.
 *  @property {number} y The Y-coordinate.
 */
function Point(x, y) {
  return {
        x: x,
        y: y
    };
}

/**
 * @returns {Point} The location of the event.
 */
var getEventLocation = function(e, type) {
    ...
    return new Point(x, y);
};
les orignaux
la source
Lorsque je fais cela mais que j'utilise le compilateur de fermeture Google, j'obtiens un avertissement: "impossible d'instancier un non-constructeur". J'ai essayé d'ajouter @constructor à la fonction (au-dessus de @return) mais cela n'a pas aidé. Si quelqu'un sait comment résoudre ce problème, faites-le moi savoir. Merci!
AndroidDev
2
@AndroidDev c'est parce que la fonction Pointn'est pas un constructeur, pour changer qui remplace le corps de la Pointfonction parthis.x = x; this.y = y;
Feirell
1
Je ne vois pas la raison pour laquelle nous devons utiliser new ici, pourquoi ne pas simplement retourner Point (x, y)?
CHANist
@CHANist, la newsyntaxe consiste à créer une instance à partir du constructor. Sans new, le contexte thisserait le contexte mondial. Vous pouvez essayer de créer une instance sans newvoir l'effet.
Akash