JSDoc: Objektstruktur zurückgeben

143

Wie kann ich JSDoc über die Struktur eines zurückgegebenen Objekts informieren? Ich habe die @return {{field1: type, field2: type, ...}} descriptionSyntax gefunden und ausprobiert:

/**
 * 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 wird, heißt es in der resultierenden Dokumentation einfach:

Returns: 
    The location of an event
    Type: Object

Ich entwickle eine API und brauche Leute, die über das Objekt Bescheid wissen, das sie zurückgeben werden. Ist das in JSDoc möglich? Ich verwende JSDoc3.3.0-beta1.

Schwarzer Wolf
quelle
Ich weiß, dass dies @typedefeine Problemumgehung / Lösung ist, aber es scheint seltsam, dass dies nicht mit wörtlichen Objekten funktioniert. Wenn jemand in Zukunft darauf stößt (wie ich), habe ich ein Problem hinzugefügt, github.com/jsdoc/jsdoc/issues/1678 , das mehr Informationen als diese Seite enthalten könnte.
Leszek

Antworten:

262

Definieren Sie Ihre Struktur separat mit einem @typdef :

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

Und verwenden Sie es als Rückgabetyp:

/**
 * 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
quelle
2
Vielen Dank. Mehrere @returnAnweisungen funktionieren zwar, aber sie werden in der Ausgabe so aufgelistet, als wären sie mehrere Rückgaben (Ein Aufzählungspunkt point - Objectund dann zwei weitere Aufzählungspunkte für point.x - Numberund point.y - Number). Obwohl ich damit leben kann, gibt es vermutlich keine Möglichkeit, eine komprimierte Ausgabe des zurückgegebenen Objekts zu erhalten. Oder zumindest die Einträge für point.xund point.yeingerückt?
BlackWolf
1
Ja, das scheint die beste Option zu sein. Ich dachte, es könnte eine Möglichkeit geben, eine nicht benannte Rückgabeentität zu haben, aber der @typedefAnsatz ist der klarste in Bezug auf die Dokumentationsausgabe, danke!
BlackWolf
groovig, entfernte die erste Option als 2. Option ist einfach am besten.
BGerrissen
1
Sie sollten eine @innerDefinition hinzufügen oder eingeben, die globalin der Dokumentation enthalten ist. +1
Onur Yıldırım
1
Ich habe immer benutzt @typedef {Object} Point. Die Verwendung dieses zweizeiligen Formulars wird Pointin PhpStorm mit der Meldung "Nicht aufgelöste Variable oder Typ Point" hervorgehoben. Die @typedefDokumente unterstützen dies, aber ich möchte diese Antwort nicht bearbeiten, wenn es sich um eine gültige Variante handelt.
David Harkness
22

Als Alternative zu den bereits veröffentlichten Vorschlägen können Sie dieses Format verwenden:

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

Dies ergibt die folgende Dokumentationsausgabe:

    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
quelle
17

Eine saubere Lösung besteht darin, eine Klasse zu schreiben und diese zurückzugeben.

/** 
 *  @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);
};
Elche
quelle
Wenn ich dies tue, aber den Google Closure Compiler verwende, wird eine Warnung angezeigt: "Nicht-Konstruktor kann nicht instanziiert werden". Ich habe versucht, der Funktion @constructor hinzuzufügen (über dem @return), aber es hat nicht geholfen. Wenn jemand weiß, wie man das behebt, lass es mich wissen. Vielen Dank!
AndroidDev
2
@AndroidDev Dies liegt daran, dass die Funktion Pointkein Konstruktor ist, um zu ändern, die den Körper der PointFunktion durchthis.x = x; this.y = y;
Feirell
1
Ich sehe keinen Grund, warum wir hier new verwenden müssen, warum nicht einfach Punkt (x, y) zurückgeben?
CHANist
@CHANist, newSyntax ist das Erstellen einer Instanz aus dem constructor. Ohne wäre newder Kontext von thisder globale Kontext. Sie können versuchen, eine Instanz zu erstellen, ohne newden Effekt zu sehen.
Akash