Richtiger Weg, um offene Argumentfunktionen in JSDoc zu dokumentieren

82

Angenommen, Sie haben etwa Folgendes:

var someFunc = function() {
    // do something here with arguments
}

Wie würden Sie korrekt dokumentieren, dass diese Funktion eine beliebige Anzahl von Argumenten in JSDoc annehmen kann? Dies ist meine beste Vermutung, aber ich bin nicht sicher, ob es richtig ist.

/**
 * @param {Mixed} [...] Unlimited amount of optional parameters
 */
var someFunc = function() {
    // do something here with arguments
}

Verwandt mit: php - Wie man eine variable Anzahl von Parametern dokumentiert

kflorence
quelle

Antworten:

117

Die JSDoc-Spezifikationen und der Closure Compiler von Google machen dies folgendermaßen:

@param {...number} var_args

Wobei "Zahl" die Art der erwarteten Argumente ist.

Die vollständige Verwendung würde dann wie folgt aussehen:

/**
* @param {...*} var_args
*/
function lookMaImVariadic(var_args) {
    // Utilize the `arguments` object here, not `var_args`.
}

Beachten Sie den Kommentar zur Verwendung arguments(oder einem Versatz von arguments) für den Zugriff auf Ihre zusätzlichen Argumente. var_argsEs wurde nur verwendet, um Ihrer IDE zu signalisieren, dass das Argument tatsächlich existiert.

Ruheparameter in ES6 können den realen Parameter noch einen Schritt weiter führen, um die bereitgestellten Werte zu erfassen (daher ist keine weitere Verwendung argumentserforderlich):

/**
* @param {...*} var_args
*/
function lookMaImES6Variadic(...var_args) {
    // Utilize the `var_args` array here, not `arguments`.
}
Dawson Toth
quelle
Dies ist wahrscheinlich so nah an einer Antwort wie wir bekommen können :)
Kflorence
2
Erwähnenswert ist auch, dass die internen JSDoc-Dateien von WebStorm (DHTML.js usw.) dieselbe Syntax verwenden. Vielleicht ist es der De-facto-Standard.
Scott Rippey
2
es wird auch hier ziemlich gut beschrieben: usejsdoc.org/tags-param.html (Abschnitt 'Ermöglicht die Wiederholung eines Parameters')
Francois
Diese Antwort sollte bearbeitet werden, um die Antwort von Adrian Holovaty zu integrieren: Es muss eine tatsächliche Variable namens var_argsoder was auch immer Sie als einzigen Parameter aufrufen möchten. Trauriger Hack.
Oli
1
Mit der Hinzufügung von Ruheparametern in ES6 ist dies viel sinnvoller. /** @param {...Function} tasks The tasks. */ function waterfallTasks(...tasks) {Ruheparameter haben immer eine funktionale Präsenz in den Parametern.
Shibumi
25

Wie das geht, wird jetzt in der JSDoc-Dokumentation beschrieben und es wird ein Auslassungszeichen verwendet, wie es in den Closure-Dokumenten der Fall ist.

@param {...<type>} <argName> <Argument description>

Sie müssen einen Typ angeben, um die Auslassungspunkte zu verfolgen. Sie können jedoch einen verwenden *, um das Akzeptieren von Daten zu beschreiben, oder den |, um mehrere akzeptable Typen zu trennen. In der generierten Dokumentation beschreibt JSDoc dieses Argument als wiederholbar , genauso wie es optionale Argumente als optional beschreibt .

Bei meinen Tests war es nicht erforderlich, ein Argument in der eigentlichen Definition der Javascript-Funktion zu haben, sodass Ihr tatsächlicher Code nur leere Klammern enthalten kann, d function whatever() { ... }. H.

Einzeltyp:

@param {...number} terms Terms to multiply together

Jeder Typ (im folgenden Beispiel bedeutet der Mittelwert itemsin eckigen Klammern, dass er sowohl als optional als auch als wiederholbar gekennzeichnet ist):

@param {...*} [items] - zero or more items to log.

Mehrere Typen benötigen Klammern um die Typliste mit den Auslassungspunkten vor dem Eröffnungs-Paren:

@param {...(Person|string)} attendees - Meeting attendees, listed as either 
                                        String names or {@link Person} objects
Daniel Baird
quelle
1
Und was ist mit Objekten, die als Schlüssel-Wert-Paare verwendet werden? Zur Zeit benutze ich: @param {{...(key: value)}} [config] - specific configs for this transferaber habe mich gefragt, ob das richtig ist?
Max
@Max Ich kann den Dokumenten nicht entnehmen, ob dies der offizielle richtige Weg ist, aber es sieht so aus, als ob es wie erwartet funktionieren sollte. Wenn es also eine Ausgabe erzeugt, mit der Sie einverstanden sind, würde ich sie verwenden :)
Daniel Baird
10

Aus der JSDoc-Benutzergruppe :

Es gibt keinen offiziellen Weg, aber eine mögliche Lösung ist folgende:

/**
 * @param [...] Zero or more child nodes. If zero then ... otherwise ....
 */

Die eckigen Klammern geben einen optionalen Parameter an, und die ... würden (für mich) "eine beliebige Zahl" anzeigen.

Eine andere Möglichkeit ist diese ...

/**
 * @param [arguments] The child nodes.
 */

In jedem Fall sollte kommuniziert werden, was Sie meinen.

Es ist zwar etwas veraltet (2007), aber mir ist nichts Aktuelleres bekannt.

Wenn Sie den Parametertyp als 'gemischt' dokumentieren müssen, verwenden Sie {*}wie in @param {*} [arguments].

Hashwechsel
quelle
6
Es macht mir nichts aus, wenn meine Antwort abgelehnt wird, aber ich erwarte einen Kommentar, der erklärt, warum Sie es getan haben (wer auch immer Sie sind). Wenn Sie denken, dass es falsch ist, lassen Sie mich - und uns alle - wissen, warum.
Hashchange
2
Meine IDE der Wahl (WebStorm 8.0.1) unterstützt die Syntax Nr. 2 @param [arguments](oder auch @param {*} [arguments]) sowie die vom Google Closure-Compiler festgelegte Syntax (in einer anderen Antwort erwähnt). @param [...]wird nicht unterstützt.
Mistaecko
@mistaecko aber nur mit benannten Parametern richtig? Das ist es, was ich nicht benutze, also ist dies keine akzeptable Antwort für mich ...
Sebastian
10

Ich habe mich eine ganze Weile damit beschäftigt. So geht's mit Google Closure Compiler:

/**
* @param {...*} var_args
*/
function my_function(var_args) {
    // code that accesses the magic 'arguments' variable...
}

Der Schlüssel besteht darin, Ihrer Funktion einen var_argsParameter zu geben (oder wie auch immer Sie ihn in Ihrer @paramAnweisung nennen), obwohl die Funktion diesen Parameter nicht tatsächlich verwendet.

Adrian Holovaty
quelle