JS API 文档 [, arg ] vs , [ arg ]答案

【问题标题】：JS API documentation [, arg ] vs , [ arg ]JS API 文档 [, arg ] vs , [ arg ]
【发布时间】：2014-03-27 03:30:44
【问题描述】：

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

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

有时像这样：

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

把逗号放在括号内和括号外的意思不同吗？

【问题讨论】：

意思没有区别。前者更正确，因为只有在传递参数时才需要逗号（方括号表示方法签名的可选部分）。
你有第二个例子吗？第一个由getJSON 使用。第二个可能意味着参数必须是一个数组，但我需要看一个具体的例子。
我不知道有任何标准描述了这种表示法。如果确实没有，则含义由创建文档的开发人员定义。如果有这样的标准，那并不一定意味着开发者在遵循这个标准。
IMO，这个问题缺乏细节。如果没有具体的真实示例，我们如何知道意图是什么？
这是实际文档中后一种语法的示例：api.highcharts.com/highcharts#Chart

标签： javascript

【解决方案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(){}) 都是有效的（当然你可以省略结尾的undefineds）。

记录可变参数的一种明确方法是使用嵌套和替代方法，另请参阅Documentation for optional parameters in JavaScript。

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

【讨论】：

您在解释第二种语法时是否引用了一些特定的文档语料库？例如。这是在 jQuery 文档中使用的吗？
如果这是真的，很高兴知道！我得测试一下。我认为 jQuery 几乎总是使用前一种语法，为了方便起见，我只是在后一种语法的示例中使用了相同的定义，但这里是实际文档中后一种语法的示例：api.highcharts.com/highcharts#Chart
不，这是我个人的解释。实际上，这也可能意味着data 是一个数组（就像[data...] 一样）：-/ 不过，也许我会在通用文档指南中找到参考。
@RobbyAllsopp：这个例子似乎符合我的解释。对于addAxis (Object options, [Boolean isX], [Boolean redraw], [Mixed animation])，如果这意味着与第一种语法相同是没有意义的，因为布尔值无法区分。也许他们也可能意味着addAxis (Object options [, Boolean isX [, Boolean redraw [, Mixed animation]]])，但是不允许传递addAxis({}, undefined, false)（不确定这是否是有效）
@Asad：我找不到明确的参考，但我声称这是一个常见的约定。 RobbyAllsopp：The code 证实了我的发现，尽管 isX 实际上不是可选的，但它适用于其他两个具有默认值但不能简单地省略的参数。