JSDoc: Devolver estructura de objetos

Question

JSDoc: Devolver estructura de objetos

¿Cómo puedo decirle a JSDoc sobre la estructura de un objeto que se devuelve? He encontrado la sintaxis @return {{field1: type, field2: type, ...}} description y la he probado:

/**
 * 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};
}

Mientras que esto analiza con éxito, la documentación resultante simplemente indica:

Returns: 
    The location of an event
    Type: Object

Estoy desarrollando una API y necesito que la gente sepa sobre el objeto que se les devolverá. ¿Es esto posible en JSDoc? Estoy usando JSDoc3.3. 0-beta1.

77

javascript jsdoc documentation-generation code-documentation jsdoc3

Author: BlackWolf, 2015-02-27

Source

2 answers

Una solución limpia es escribir una clase y devolverla.

/** 
 *  @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);
};

12

Author: mooses,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2016-04-21 04:26:36

score 140 · Accepted Answer

Define por separado:

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

Y uso:

/**
 * 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};
}