Comment interpréter la documentation pour les parameters JavaScript facultatifs

Dans la documentation de addEventListener je vois le modèle suivant:

 target.addEventListener(type, listener[, useCapture]); 

Maintenant, je comprends que useCapture est un paramètre facultatif. Pourquoi le [ commence-t-il alors avant la virgule ( , ) et non immédiatement après la virgule qui suit le paramètre listener ? Qu’est-ce que la paire de [] renfermant suggère réellement, mis à part le fait que useCapture est facultatif? J’ai également vu des modèles de documentation similaires dans la documentation jQuery, par exemple la documentation de la méthode on () .

 .on( events [, selector ] [, data ], handler(eventObject) ) 

Les crochets signifient que la chose à l’intérieur est optionnelle – que vous l’ayez ou pas. C’est une manière concise d’énumérer les formulaires d’invocation valides.

L’exemple de base

target.addEventListener (type, écouteur [, useCapture]);

Il existe deux formes valides:

 target.addEventListener(type, listener ); // without target.addEventListener(type, listener, useCapture); // with 

Si la virgule était en dehors des crochets, les deux formulaires seraient

 target.addEventListener(type, listener, ); // without (syntax error) target.addEventListener(type, listener, useCapture); // with 

L’exemple jQuery

.on (événements [, sélecteur] [, données], gestionnaire);

Celui-ci est un peu délicat. Le sélecteur et les données sont facultatifs. Il existe donc quatre formes valides:

 .on( events , handler ); // without both .on( events , data, handler ); // without selector, with data .on( events, selector , handler ); // with selector, without data .on( events, selector, data, handler ); // with both 

Le problème est que les deuxième et troisième formes ont trois parameters, donc la façon dont les arguments seront interprétés n’est pas évidente. Il semble que jQuery décide en fonction du type de l’argument du milieu: s’il s’agit d’une chaîne, la troisième forme est choisie; sinon la deuxième forme est choisie.

Ainsi, les éléments suivants auront "hi" comme sélecteur et rien comme argument de données:

 .on( events , "hi", handler ); // "hi" is the selector (!) 

Pour forcer jQuery à utiliser "hi" comme argument de données, null doit être indiqué pour le sélecteur:

 .on( events, null , "hi", handler ); // "hi" is the data argument 

Ceci est sans équivoque la quasortingème forme, et la documentation dit qu’un sélecteur null est traité de la même façon qu’un sélecteur omis.

Un exemple nested

Dans la documentation, vous verrez souvent des crochets nesteds. Voici un exemple simplifié de la documentation de la commande Unix man :

man [–warnings [= type]] page

Cela signifie que les formulaires suivants sont valides:

 man javac # without outer man --warnings javac # with outer (without inner) man --warnings=number javac # with outer (with inner) 

Mais ce qui suit ne serait pas valide:

 man =number javac # is this with or without outer?