So dokumentieren Sie die Rückgabe in JavaScript

Question

Ich schreibe meine eigene Bibliothek für das Projekt bei der Arbeit für eine Browser-Anwendung und ich habe das gleiche alte Problem, wie man den Code kommentieren.

Ich versuche, die JsDoc Syntax zu folgen, aber wird wahrscheinlich die Google Closure Compiler Weg fortsetzen. Ich könnte am Ende zwei @ return und @ returns-Tags in der Dokumentation verwenden, nur aus Gründen der Portabilität (wenn ich die automatische Generierung der Dokumentation einstelle).

Nun, die Frage, Wie dokumentieren Sie die Rückgabe eines benutzerdefinierten anonymen Objekts aus einer Funktion? Zum Beispiel:

return { 
    username: 'username', 
    password: 'password', 
    enabled: true 
}; 

JsDoc hat ein Beispiel dafür, wie ein @param Objekt mit bestimmten Bereichen zu erwarten, zu dokumentieren, aber nicht den @returns-Tag. In ähnlicher Weise ist die Google Closure Compiler-Dokumentation eines Datensatztyps vage und es gibt kein Beispiel dafür.

Answer 1

Wenn dieses in Anfang der Funktion

function myFunction() { 
    /** 
    * Description of my function 
    * @return {!Object.<string, string|boolean>} Returns an object containing username, password and enabled information 
    */ 

    // Do stuff 
    return { 
     username: 'username', 
     password: 'password', 
     enabled: true 
    } 
} 

Answer 2

Der Closure-Compiler verwendet eine Teilmenge der JSDoc annotations (und fügt ein paar seiner eigenen). Das komplette Set finden Sie unter annotation reference for the compiler. Eine JSDoc-Annotation ähnelt einer JavaDoc-Annotation und ist ein Kommentarblock, der mit /** (zwei Sterne) beginnt. Während jede Zeile des Kommentars oft mit ihrer eigenen * beginnt, ist das eine Konvention, die nicht erforderlich ist. Pro Zeile ist nur ein JSDoc-Tag zulässig, die Argumente für ein Tag können sich jedoch über mehrere Zeilen erstrecken.

Die Annotation gilt normalerweise für die folgende Anweisung. Hier sind einige Beispiele:

Variable

/** @type {string} */ var a; 

Typ Cast

var b = /** @type {string} */ (window['foo']); 

Notiz die zusätzliche Klammer

benannte Funktion

/** 
* @param {string} bar 
* @return {boolean} 
*/ 
function foo(bar) { return true; } 

Ausdrücke

Funktion

/** @type {function(string):boolean} */ 
var foo = function(bar) { return true; } 

var foo2 = 
    /** 
    * @param {string} bar 
    * @return {boolean} 
    */ 
    function(bar) { return true; } 

Typedef

Komplexe Typen (einschließlich Gewerkschaften und Datensatztypen) können für die Bequemlichkeit und Wartbarkeit mit einem typedef aliased werden. Diese Anmerkungen können lang sein, können aber zur besseren Lesbarkeit über mehrere Zeilen verteilt werden.

/** @typedef {{ 
*    foo:string, 
*    bar:number, 
*    foobar:number|string 
*   }} 
*/ 
var mytype; 

Für Ihr ursprüngliches Beispiel gibt es mehrere Möglichkeiten, einen solchen Funktionsrückgabewert zu kommentieren. Eines der spezifischen und immer noch bequem ist der Satzart:

/** @return {{username:string, password:string, enabled:boolean}} */ 
function() { 
    return { 
    username: 'username', 
    password: 'password', 
    enabled: true 
    } 
} 

Beachten Sie die zusätzlichen {}. Beachten Sie auch, dass Datensatztypen die Umbenennung von Eigenschaften nicht verhindern.

Diese Anmerkung teilt dem Compiler mit, dass die Funktion einen anonymen Typ mit den Eigenschaften username, password und enabled zurückgibt. Andere gültige Optionen wären, eine Schnittstelle anderswo zu definieren und den Rückgabewert als diese Schnittstelle typisieren zu lassen. Die am wenigsten spezifische Annotation wäre Object oder *.

Um eine breite Palette möglicher Annotationen zu sehen, werfen Sie einen Blick auf die extern files in the Compiler project.

Answer 3

Eine der netten und portablen Möglichkeiten, es zu tun, ist wie folgt, mit Return als Schlüsselwort. https://github.com/senchalabs/jsduck/wiki/%40return

/** 
* @return {object} return An object with the following properties 
* @return {string} return.username Some username 
* @return {string} return.password Some password 
* @return {boolean} return.enabled Is the user enabled? 
*/ 
function getObj() { 
    return { 
     username: 'username', 
     password: 'password', 
     enabled: true 
     }; 
} 

Wenn Sie es an mehreren Stellen verwenden, würden Sie es duplizieren müssen, oder verwenden Sie @typedef, aber ich habe nicht herausgefunden, wie Kommentare hinzufügen zu @typedef so verwende ich so etwas wie die folgenden

/** 
* @typedef {username:string, password:string, enabled:boolean} MyType 
* 
* username: The name of the user 
* password: Some password 
* enabled: Is the user enabled? 
*/ 

/** 
* @return {MyType} 
*/ 
function getObj() { 
    return { 
     username: 'username', 
     password: 'password', 
     enabled: true 
     }; 
} 

Sie können auch den Vorschlag, versuchen hier How can I document a type in webstorm using just jsdoc?