Wie kann ich in JsDoc void zurückgeben?

80

Gibt es eine bestimmte Möglichkeit, eine Methode oder eine Funktion zu deklarieren, um in JsDoc void zurückzugeben? Derzeit bin ich der Überzeugung, dass dies voidder Standardrückgabewert ist, und andere Rückgabewerte müssen speziell angegeben werden:

/**
 * @return {Integer} The identifier for ...
 */
javascript ide jsdoc Turm
quelle
eslint.org/docs/rules/valid-jsdoc sagt @returns {void}Ahhh, jemand hat es bereits erwähnt: stackoverflow.com/a/45450508/470749
Ryan

Antworten:

93

Ich glaube nicht, dass Sie in JsDoc aus einer Reihe von Typen auswählen müssen ... Sie können einen beliebigen Typnamen verwenden (die geschweiften Klammern zeigen an, dass es sich um einen Typ handelt), also können Sie einfach Folgendes tun:

@return {Void}

Obwohl dies für JavaScript wahrscheinlich korrekter ist:

@return {undefined}
David Tang
quelle
kann auch sein @returns {void}?
Hellboy
8
@ Eugene nullist nicht unbedingt das gleiche wieundefined
BadHorsie
6
@return {Void}löst eine Code-Inspektionswarnung in IntelliJ IDE aus @return {undefined}und @return {void}nicht.
Shanimal
4
nullist nie das gleiche wie undefined. Wenn etwas null ist, ist es immer noch definiert, aber ohne Wert. Undefiniert ist, na ja, nicht definiert :-)
Magnus Eriksson
3
In den Ecmascript-Spezifikationen sind die Sprachtypen aufgeführt. Der vom voidOperator zurückgegebene Wert ist undefined. Der Name des Werttyps undefinedlautet Undefined, obwohl er typeof undefinedausgewertet wird "undefined". Der Name Voidist in den Ecmascript-Spezifikationen nicht definiert.
Aaron Mansheim
104

Closure Compiler

Laut der Dokumentation des Google Closure Compiler sollte die Annotation @return weggelassen werden, wenn nichts zurückgegeben wird.

Wenn es keinen Rückgabewert gibt, verwenden Sie kein @ return-Tag.

Quelle: https://developers.google.com/closure/compiler/docs/js-for-compiler#tags

jsdoc-toolkit

In der weiteren Dokumentation wird jedoch auch angegeben, dass returnType und returnDescription optionale Parameter sind.

returnType - Optional: Der Typ des Rückgabewerts.

returnDescription - Optional: jede zusätzliche Beschreibung.

Quelle: https://code.google.com/p/jsdoc-toolkit/wiki/TagReturns

Zusammenfassung

Sie können die Rückgabeanmerkung entweder weglassen oder ohne Parameter einfügen.

Brent Robinson
quelle
10
Diese Antwort ist tatsächlich besser als die akzeptierte. Wenn Ihre Funktion kein Ergebnis zurückgibt, sollten Sie nicht sagen, dass es zurückgibt, undefinedda dies bereits in Javascript impliziert ist und bei jedem, der Ihre Dokumente liest, Verwirrung stiften kann.
Lucio Paiva
2
Nein, ich bin anderer Meinung und sage, dass dies keine gute Idee ist. Wenn etwas fehlt, wissen Sie nicht, ob es beabsichtigt war oder nicht. Indem Sie den Rückgabetyp explizit angeben, selbst wenn Sie sich undefineddazu zwingen, Ihre Absicht darzulegen, ist dies auch gut, wenn Sie ihn später lesen. Zur Verdeutlichung sage ich nicht, dass man eine nutzlose JS-Anweisung einschließen sollte, ich sage, dass man immer eine JSDoc- @returnsAnweisung einschließen sollte (ich bin gegen nutzlosen Code, aber nicht gegen "nutzlose" Kommentare).
Mörre
IMO ist es sinnvoll, einen Rückgabetyp von undefined anzugeben, wenn es möglich ist, dass Ihre Funktion oder Methode einen anderen Wert zurückgibt. In diesem Fall erhalten Sie @returns {Array|undefined} - returns array if operation successful, otherwise returns undefined
Folgendes
15

Betrachten Sie die von ihnen verwendeten ESlint-Dokumente @returns {void}

Quelle: http://eslint.org/docs/rules/valid-jsdoc

Da ich @returnsfür jede Funktion eine angeben muss, um Tests zu bestehen, um Code für bestimmte Projekte zu pushen, ist dies in meinem Fall erforderlich.

primetimejas
quelle
1

Wenn Sie laut sagen müssen, dass nichts zurückgegeben wird, können Sie dies in der Freiformbeschreibung sagen . Dies ist nützlich, um Situationen zu klären, in denen ein Benutzer möglicherweise erwartet, dass etwas zurückgegeben wird. Natürlich sollte die richtige Benennung der Funktion und der Parameter allein den erwarteten Rückgabetyp deutlich machen, aber dies ist möglicherweise nicht immer möglich.

/**
 * This is a funny function. Returns nothing.
 * @param {string} a joke.
 */
var funny = function (joke) {
  console.log(joke);
};
Akseli Palén
quelle