Korrekte Methode zum Dokumentieren von Funktionen mit offenem Argument in JSDoc

Nehmen wir an, Sie haben etwas wie das Folgende:

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 mir 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

Das JSDoc-Spezifikationen und Closure Compiler von Google mach es so:

@param {...number} var_args

Wobei “Nummer” der Typ der erwarteten Argumente ist.

Die vollständige Verwendung davon 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 ein Offset von arguments), um auf Ihre zusätzlichen Argumente zuzugreifen. var_args es hat Ihrer IDE nur signalisiert, dass das Argument tatsächlich existiert.

Restparameter in ES6 kann den realen Parameter noch einen Schritt weiter bringen, um bereitgestellte Werte zu umfassen (also keine Verwendung mehr von arguments ist notwendig):

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

Wie das geht ist jetzt beschrieben in der JSDoc-Dokumentation und verwendet Auslassungspunkte wie die Closure-Dokumentation.

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

Sie müssen einen Typ angeben, der nach den Auslassungspunkten steht, aber Sie können a verwenden * um das Akzeptieren von irgendetwas zu beschreiben, oder verwenden Sie die | um mehrere akzeptable Typen zu trennen. In der generierten Dokumentation beschreibt JSDoc dieses Argument als wiederholbargenauso wie optionale Argumente beschrieben werden Optional.

In meinen Tests war es nicht erforderlich, ein Argument in der eigentlichen Javascript-Funktionsdefinition zu haben, sodass Ihr tatsächlicher Code nur leere Klammern haben kann, dh function whatever() { ... }.

Einzeltyp:

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

Beliebiger Typ (im Beispiel unten bedeuten die eckigen Klammern items wird sowohl als optional als auch als wiederholbar gekennzeichnet):

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

Mehrere Typen benötigen Klammern um die Typliste, mit Auslassungspunkten vor dem öffnenden Klammern:

@param {...(Person|string)} attendees - Meeting attendees, listed as either 
                                        String names or {@link Person} objects

Von dem JSDoc-Benutzergruppe:

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

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

Die eckigen Klammern zeigen einen optionalen Parameter an, und das … würde (für mich) “irgendeine willkürliche Zahl” anzeigen.

Eine andere Möglichkeit ist diese…

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

So oder so sollte kommunizieren, was Sie meinen.

Es ist zwar etwas älter (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 ziemlich lange damit herumgeschlagen. So geht’s mit dem Google Closure Compiler:

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

Der Schlüssel ist, Ihrer Funktion a zu geben var_args Parameter (oder wie auch immer Sie es in Ihrer @param -Anweisung), obwohl die Funktion diesen Parameter nicht wirklich verwendet.