How to interpret documentation for optional JavaScript parameters [duplicate]

by

Square brackets mean the thing inside them is optional – either you have it or you don’t. It is a concise way of listing the valid invocation forms.

The Basic Example

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

There are two valid forms:

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

If the comma was outside the square brackets the two forms would be

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

The jQuery Example

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

This one is a bit tricky. The selector and data are optional so there are four valid forms:

.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

The problem is that the second and third forms both have three parameters, so it’s not obvious how the arguments will be interpreted. It appears that jQuery decides based on the type of the middle argument: if it’s a string the third form is chosen; otherwise the second form is chosen.

So the following will have "hi" as the selector and nothing as the data argument:

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

To force jQuery to use "hi" as the data argument, null must be given for the selector:

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

This is unambiguously the fourth form, and the docs say that a null selector is treated the same an omitted selector.

A Nested Example

In documentation you’ll often see nested square brackets. Here is a simplified example from the documentation for the Unix command man:

man [–warnings[=type]] page

This means the following forms are valid:

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

But the following would not be valid:

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

More Related Contents:

  1. Matching text field value with array value
  2. Replacing live with on function [closed]
  3. How to Get Response From rest URL using jquery
  4. .index() only for one instance of class [closed]
  5. Direct vs. Delegated – jQuery .on()
  6. What is the best way to add options to a select from a JavaScript object with jQuery?
  7. Check if user is using IE
  8. toggle show/hide div with button?
  9. jQuery selector for id starts with specific text [duplicate]
  10. How to filter JSON Data in JavaScript or jQuery?
  11. How can I determine if an image has loaded, using Javascript/jQuery?
  12. Call javascript function after script is loaded
  13. Dynamically loading css stylesheet doesn’t work on IE
  14. How to add a “readonly” attribute to an ?
  15. How can I detect whether an iframe is loaded?
  16. Fade In on Scroll Down, Fade Out on Scroll Up – based on element position in window
  17. Content Security Policy: The page’s settings blocked the loading of a resource
  18. How to convert the following table to JSON with javascript?
  19. HTML 5 – Play file at certain time point
  20. offsetTop vs. jQuery.offset().top
  21. Cancel event on input type=”file”
  22. Change matching words in a webpage’s text to buttons
  23. TypeError: $(…).modal is not a function with bootstrap Modal
  24. Javascript – Stop form submit depending on ajax response [duplicate]
  25. Prevent Highlight of Text Table
  26. User Activity Tracking using javascript library [closed]
  27. Force hide address bar in Chrome on Android
  28. jQuery JSONP ajax, authentication header not being set
  29. Error: Permission denied to access property ‘handler’
  30. jQuery SVG vs. Raphael [closed]

Leave a Comment