1

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, textStatus, jqXHR ) ] )

and sometimes like this:

jQuery.getJSON( url, [data], [success( data, textStatus, jqXHR )] )

Does putting the commas inside the brackets have a different meaning than outside the brackets?

Improve this question
5
  • 1
    There is no difference in meaning. The former is more correct because you only need the comma if you are passing the argument (square brackets denote an optional part of the method signature). Commented Mar 26, 2014 at 17:06
  • 2
    Do you have an example of the second? The first is used by getJSON. The second might mean that the argument has to be an array, but I'd need to see a specific example. Commented Mar 26, 2014 at 17:06
  • I'm not aware of any standard that describes this notation. If indeed there is none, then the meaning is defined by the developer that created the documentation. If there is such a standard, then that doesn't necessarily mean that the developer is following the standard. Commented Mar 26, 2014 at 17:09
  • IMO, the question lacks detail. How can we know what the intent is without specific, real-world examples? Commented Mar 26, 2014 at 17:13
  • here's an example of the latter syntax in actual documentation: api.highcharts.com/highcharts#Chart Commented Mar 26, 2014 at 17:58

1 Answer 1

Reset to default
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.

Improve this answer
Sign up to request clarification or add additional context in comments.

6 Comments

Is there some specific documentation corpus you are referring to in your interpretation of the second syntax? Eg. is this in use in the jQuery docs?
If this is true, good to know! I'll have to test it out. I think jQuery pretty much always uses the former syntax, and I just used the same definition for my example of the latter syntax for sake of ease, but here's an example of the latter syntax in actual documentation: api.highcharts.com/highcharts#Chart
No, that's my personal interpretation. Actually it also could mean that data is an array (like [data...] would) :-/ Maybe I will find a reference in a common documentation guideline, though.
@RobbyAllsopp: That example seems to match my explanation. For addAxis (Object options, [Boolean isX], [Boolean redraw], [Mixed animation]) it would not make sense if this meant the same as the first syntax, as the booleans were undistinguishable. Maybe they also could have meant addAxis (Object options [, Boolean isX [, Boolean redraw [, Mixed animation]]]), which however would not allow passing addAxis({}, undefined, false) (not sure if that is valid)
@Asad: I couldn't find a definitive reference, but I claim this to be a common convention. RobbyAllsopp: The code confirms my findings, even though isX is not optional actually it holds for the other two arguments which have a default value but cannot simply be left out.
|

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.