javascript - JS API 文档 [, arg ] vs , [ arg ]

Question

在阅读各种 API 的文档时，我注意到有时函数定义会这样写:

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

有时像这样:

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

括号内的逗号与括号外的逗号的含义是否不同？

Answer 1

遵循utility argument syntax惯例和nested arguments就像 docopt ，对位置参数进行一些转移:

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

这意味着可以省略该参数，并且 success 回调可能出现在第二位。全部 $.getJSON(url)、$.getJSON(url, {})、$.getJSON(url, function(){}) 和 $.getJSON(url, {}, function(){}) 有效。 API 可以确定第二个参数是否是 data 对象，或者第三个参数是否作为第二个参数传递。

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

这意味着可以省略参数值，但success回调(如果明显)必须始终排在第三位。全部 $.getJSON(url, undefined, undefined)、$.getJSON(url, {}, undefined)、$.getJSON(url, undefined, function(){}) 和 $.getJSON(url, {}, function(){}) 是有效的(尽管您可以省略尾随的 undefined当然)。

记录可变参数的显式方法是使用嵌套和替代方案，另请参阅 Documentation for optional parameters in JavaScript .

但是，如果不知道描述开发人员所使用的文档风格的标准或引用，我们永远不知道他的真实意图。他可能也认为他们是平等的。