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。

但是，如果不知道描述开发人员使用的文档样式的标准或参考，我们永远不会知道他的实际意图。他可能也认为它们是平等的。