JSDoc: Rückgabeobjektstruktur

Question

Wie kann ich JSDoc über die Struktur eines Objekts informieren, das zurückgegeben wird. Ich habe die @return {{field1: type, field2: type, ...}} description Syntax gefunden und versuchte es:

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

Während dies erfolgreich analysiert, die daraus resultierende Dokumentation einfach erklärt:

Returns: 
    The location of an event 
    Type: Object 

ich eine API entwickle und müssen die Menschen über das Objekt zu wissen, dass sie wird zurückgegeben. Ist das in JSDoc möglich? Ich benutze JSDoc3.3.0-beta1.

Answer 1

definieren seperatly:

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

und Verwendung:

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

Answer 2

Eine saubere Lösung ist eine Klasse zu schreiben, und das zurück.

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