Richtiger Weg, um offene Argumentfunktionen in JSDoc zu dokumentieren

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

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`.
}

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

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].

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.