Poprawny sposób dokumentowania otwartych funkcji argumentowych w JSDoc

Powiedzmy, że masz coś takiego:

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

Jak poprawnie udokumentowałbyś, że ta funkcja może przyjmować dowolną liczbę argumentów w JSDoc? To moje najlepsze przypuszczenie, ale nie jestem pewien, czy jest poprawne.

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

Związane z: php - Jak dociągnąć zmienną liczbę parametrów

Specyfikacje JSDoc i Google Closure Compiler robią to w ten sposób:

@param {...number} var_args

Gdzie „liczba” to typ oczekiwanych argumentów.

Całkowite wykorzystanie tego wyglądałoby zatem następująco:

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

Zwróć uwagę na komentarz dotyczący wykorzystania arguments(lub pewnego przesunięcia arguments) w celu uzyskania dostępu do dodatkowych argumentów. var_argspo prostu sygnalizował twojemu IDE, że argument rzeczywiście istnieje.

Parametry resztowe w ES6 mogą posunąć rzeczywisty parametr o krok dalej, aby objąć podane wartości (więc nie argumentsma potrzeby ich więcej):

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

Jak to zrobić, jest teraz opisane w dokumentacji JSDoc i używa wielokropka, tak jak robią to dokumenty Closure.

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

Musisz podać typ, aby przejść po wielokropku, ale możesz użyć a, *aby opisać, że akceptujesz cokolwiek, lub użyć, |aby oddzielić wiele akceptowalnych typów. W wygenerowanej dokumentacji JSDoc opisuje ten argument jako powtarzalny , w ten sam sposób, w jaki opisuje argumenty opcjonalne jako opcjonalne .

Podczas moich testów nie było potrzeby posiadania argumentu w rzeczywistej definicji funkcji javascript, więc rzeczywisty kod może mieć po prostu puste nawiasy, tj function whatever() { ... }.

Pojedynczy typ:

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

Dowolny typ (w poniższym przykładzie średnia nawiasów kwadratowych itemszostanie oznaczona jako opcjonalna i powtarzalna):

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

Wiele typów wymaga nawiasów wokół listy typów, z wielokropkiem przed otwierającym oknem:

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

Z grupy użytkowników JSDoc :

Nie ma żadnego oficjalnego sposobu, ale jedno możliwe rozwiązanie jest następujące:

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

Nawiasy kwadratowe wskazują opcjonalny parametr, a ... oznaczałoby (dla mnie) „jakąś dowolną liczbę”.

Inna możliwość jest taka ...

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

Tak czy inaczej, powinieneś przekazać, co masz na myśli.

Jest trochę przestarzały (2007), ale nie znam niczego bardziej aktualnego.

Jeśli chcesz udokumentować typ parametru jako „mieszany”, użyj {*}, jak w @param {*} [arguments].

Długo się tym przejmowałem. Oto jak to zrobić za pomocą Google Closure Compiler:

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

Kluczem jest nadanie funkcji var_argsparametru (lub jakkolwiek nazwiesz to w @paraminstrukcji), nawet jeśli funkcja w rzeczywistości nie używa tego parametru.