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?

Rob Allsopp
  • 3,309
  • 5
  • 34
  • 53
  • 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). – Asad Saeeduddin Mar 26 '14 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. – Andrew Whitaker Mar 26 '14 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. – cookie monster Mar 26 '14 at 17:09
  • IMO, the question lacks detail. How can we know what the intent is without specific, real-world examples? – cookie monster Mar 26 '14 at 17:13
  • here's an example of the latter syntax in actual documentation: http://api.highcharts.com/highcharts#Chart – Rob Allsopp Mar 26 '14 at 17:58

1 Answers1

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.

Community
  • 1
  • 1
Bergi
  • 630,263
  • 148
  • 957
  • 1,375
  • 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? – Asad Saeeduddin Mar 26 '14 at 17:51
  • 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: http://api.highcharts.com/highcharts#Chart – Rob Allsopp Mar 26 '14 at 17:56
  • 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. – Bergi Mar 26 '14 at 17:56
  • @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) – Bergi Mar 26 '14 at 18:08
  • @Asad: I couldn't find a definitive reference, but I claim this to be a common convention. RobbyAllsopp: [The code](https://github.com/highslide-software/highcharts.com/blob/6e8a3245c060d5caa3ee17ae7e678520c6b14cbc/js/highstock.src.js#L14418) 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. – Bergi Mar 26 '14 at 19:34
  • @Bergi Regarding the highcharts example, I don't think this is evidence one way or another. The highcharts docs seem to use the same syntax throughout and never use the other form. What would be convincing is if we found docs that used *both* formats, and there was a meaningful distinction in how you're supposed to invoke functions that are documented under the two different formats. – Asad Saeeduddin Mar 26 '14 at 19:58