Js Api Documentation [, Arg ] Vs , [ Arg ]

When reading the documentation for various APIs I've noticed that sometimes a function definition will be written like this: jQuery.getJSON( url [, data ] [, success( data, textSta

Solution 1:

Following the utility argument syntax conventions and nested arguments like in docopt, with a little transfer for positional arguments:

jQuery.getJSON( url [, data ][, success( data, textStatus, jqXHR ) ] )
getjson url [--data=…][--success=function]

That means that the argument can be omitted, and the success callback might come at the second place. All of $.getJSON(url), $.getJSON(url, {}), $.getJSON(url, function(){}), and $.getJSON(url, {}, function(){}) are valid. The API can determine if the second parameter is a data object or whether the third argument was passed as the second.

jQuery.getJSON( url, [data], [success( data, textStatus, jqXHR )] )
getjson url --data[=…]--success[=function]

That means that the argument value can be omitted, but the success callback (if apparent) must always come third. All of $.getJSON(url, undefined, undefined), $.getJSON(url, {}, undefined), $.getJSON(url, undefined, function(){}), and $.getJSON(url, {}, function(){}) would be valid (though you can omit trailing undefineds of course).

An explicit way for documenting variadic arguments would be to use nesting and alternatives, see also Documentation for optional parameters in JavaScript.

However, without knowing the standard or reference describing the documentation style that the developer has used, we never know his actual intention. He might have considered them equal as well.