如何解释可选 JavaScript 参数的文档 [重复]答案

【问题标题】：How to interpret documentation for optional JavaScript parameters [duplicate]如何解释可选 JavaScript 参数的文档 [重复]
【发布时间】：2013-06-12 11:47:59
【问题描述】：

从documentation for addEventListener 我看到以下模式：

target.addEventListener(type, listener[, useCapture]);

现在我知道useCapture 是一个可选参数。为什么[ 在逗号 (,) 之前开始，而不是紧跟在listener 参数之后的逗号之后？除了useCapture 是可选的这一事实之外，封闭的[] 对实际上暗示了什么？我还在 jQuery 文档中看到了类似的文档模式，例如on () method documentation。

.on( events [, selector ] [, data ], handler(eventObject) )

【问题讨论】：

逗号在括号内，因为逗号属于后面的参数，否则如果你把第三个参数去掉，你会得到target.addEventListener(type, listener,)。这是可选参数的标准文档样式（用于很多语言和库） - 方括号属于文档中的 only，当您实际使用该函数时不要添加它们代码。不要太沉迷于它......

标签： javascript jquery

【解决方案1】：

方括号意味着它们里面的东西是可选的——要么你有，要么你没有。这是列出有效调用表单的简洁方式。

基本示例

target.addEventListener(type, listener[, useCapture]);

有两种有效的形式：

target.addEventListener(type, listener            ); // without
target.addEventListener(type, listener, useCapture); // with

如果逗号在方括号之外，则两种形式将是

target.addEventListener(type, listener,           ); // without (syntax error)
target.addEventListener(type, listener, useCapture); // with

jQuery 示例

.on(事件 [, 选择器] [, 数据], 处理程序);

这个有点棘手。选择器和数据是可选的，所以有四种有效的形式：

.on( events                , handler ); // without both
.on( events          , data, handler ); // without selector, with data
.on( events, selector      , handler ); // with selector, without data
.on( events, selector, data, handler ); // with both

问题是第二种和第三种形式都有三个参数，所以如何解释参数并不明显。 jQuery 似乎根据中间参数的类型来决定：如果它是字符串，则选择第三种形式；否则选择第二种形式。

所以下面将有 "hi" 作为选择器，而没有作为数据参数：

.on( events          , "hi", handler ); // "hi" is the selector (!)

要强制 jQuery 使用"hi" 作为数据参数，必须为选择器提供null：

.on( events, null    , "hi", handler ); // "hi" is the data argument

这无疑是第四种形式，文档说 null 选择器与省略选择器一样。

嵌套示例

在文档中，您经常会看到嵌套的方括号。这是 Unix 命令man 文档中的一个简化示例：

man [--warnings[=type]] 页面

这意味着以下表格是有效的：

man                   javac    # without outer
man --warnings        javac    # with outer (without inner)
man --warnings=number javac    # with outer (with inner)

但以下内容无效：

man           =number javac    # is this with or without outer?

【讨论】：