JSDoc: estructura de objeto de retorno


144

¿Cómo puedo decirle a JSDoc sobre la estructura de un objeto que se devuelve? Encontré la @return {{field1: type, field2: type, ...}} descriptionsintaxis y la probé:

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

Si bien esto se analiza con éxito, la documentación resultante simplemente establece:

Returns: 
    The location of an event
    Type: Object

Estoy desarrollando una API y necesito que las personas sepan sobre el objeto que recibirán. ¿Es esto posible en JSDoc? Estoy usando JSDoc3.3.0-beta1.


Sé que @typedefes una solución / solución, pero parece extraño que esto no funcione con objetos literales. Si alguien se topa con esto en el futuro (como lo hice), he agregado un problema github.com/jsdoc/jsdoc/issues/1678 que podría tener más información que esta página.
Leszek

Respuestas:


263

Defina su estructura por separado utilizando un @typdef :

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

Y úsalo como el tipo de retorno:

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

2
Gracias. Las @returndeclaraciones múltiples sí funcionan, pero se enumeran en la salida como si fueran varios retornos (un punto de viñeta point - Objecty luego otros dos puntos de viñeta para point.x - Numbery point.y - Number). Si bien puedo vivir con eso, supongo que no hay forma de tener una salida condensada del objeto devuelto. ¿O al menos tienen las entradas para point.xy point.ysangrado?
BlackWolf

1
Sí, esa parece ser la mejor opción. Pensé que podría haber una manera de tener una entidad de retorno sin nombre, pero el @typedefenfoque es el más claro en términos de salida de documentación, ¡gracias!
BlackWolf

maravilloso, eliminó la primera opción ya que la segunda opción es simplemente la mejor.
BGerrissen

1
Es mejor que agregue @innero escriba la definición que tendrá globalalcance en la documentación. +1
Onur Yıldırım

1
Siempre he usado @typedef {Object} Point. De hecho, el uso de este formulario de dos líneas resalta Pointen PhpStorm con el mensaje "Variable no resuelta o tipo Punto". Los @typedefdocumentos admiten esto, pero no quiero editar esta respuesta si es una variante válida.
David Harkness

22

Una alternativa a las sugerencias ya publicadas, puede usar este formato:

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

que dará la siguiente salida de documentación:

    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.

17

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

Cuando hago esto pero uso el compilador de cierre de Google, recibo una advertencia: "no se puede crear una instancia de no constructor". Intenté agregar @constructor a la función (sobre el @return) pero no me ayudó. Si alguien sabe cómo solucionarlo, avíseme. ¡Gracias!
AndroidDev

2
@AndroidDev esto se debe a que la función Pointno es un constructor, para cambiar eso reemplaza el cuerpo de la Pointfunción conthis.x = x; this.y = y;
Feirell

1
No veo la razón por la que necesitamos usar nuevo aquí, ¿por qué no simplemente devolver el Punto (x, y)?
CHANista

@CHANist, la newsintaxis es crear una instancia a partir de constructor. Sin new, el contexto de thissería el contexto global. Puede intentar crear una instancia sin newver el efecto.
Akash
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.