Poprawny sposób dokumentowania otwartych funkcji argumentowych w JSDoc

84

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

kflorence
źródło

Odpowiedzi:

119

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`.
}
Dawson Toth
źródło
To jest prawdopodobnie tak bliskie odpowiedzi, jak to tylko możliwe :)
kflorence
2
Warto również zauważyć, że wewnętrzne pliki JSDoc WebStorm (DHTML.js itp.) Używają tej samej składni. Może to de facto standard.
Scott Rippey,
2
jest to również dość dobrze opisane tutaj: usejsdoc.org/tags-param.html (sekcja 'Pozwala na powtórzenie parametru')
Francois
Tę odpowiedź należy zredagować, aby uwzględnić odpowiedź Adriana Holovaty'ego: jako jedyny parametr musi istnieć rzeczywista zmienna o nazwie var_argslub cokolwiek chcesz wywołać. Smutny hack.
Oli
1
Dodanie parametrów odpoczynku w ES6 ma o wiele większy sens. /** @param {...Function} tasks The tasks. */ function waterfallTasks(...tasks) {Pozostałe parametry zawsze mają funkcjonalną obecność w parametrach.
Shibumi
27

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
Daniel Baird
źródło
1
A co z obiektem używanym jako pary klucz-wartość? Obecnie używam: @param {{...(key: value)}} [config] - specific configs for this transferale zastanawiałem się, czy to prawda?
Max
@Max Nie mogę stwierdzić na podstawie dokumentacji, czy jest to oficjalny właściwy sposób, ale wygląda na to, że powinien działać zgodnie z oczekiwaniami. Więc jeśli generuje wyjście, z którym jesteś w porządku, użyłbym go :)
Daniel Baird
10

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

hashchange
źródło
6
Nie mam nic przeciwko temu, że moja odpowiedź zostanie odrzucona, ale spodziewam się komentarza wyjaśniającego, dlaczego to zrobiłeś (kimkolwiek jesteś). Jeśli uważasz, że to źle, daj mi - i nam wszystkim - wiedzieć, dlaczego.
hashchange,
2
Moje wybrane IDE (WebStorm 8.0.1) obsługuje składnię nr 2 @param [arguments](lub @param {*} [arguments]o to chodzi), a także składnię ustanowioną przez kompilator Google Closure (wspomniany w innej odpowiedzi). @param [...]nie jest wspierany.
mistaecko,
@mistaecko, ale tylko z podanymi parametrami, prawda? Tego nie używam, więc nie jest to dla mnie akceptowalna odpowiedź ...
Sebastian,
10

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.

Adrian Holovaty
źródło