JavaScript API 文档 - functionName([value[, arguments]]) 表示法是什么意思？

Question

此问题与：How to read API documentation for newbs? 有关。但是，该问题并未涵盖我在此处询问嵌套括号的具体格式（例如，[value[, args]]）。

虽然我认为这可能与任何 API 有关，但我正在查看 D3.js API，特别是 transition.ease()。我无法弄清楚以下是什么意思：

transition.ease([value[, arguments]])

很难找到，因为我不知道 Google 的搜索词是什么！我只想知道：

1. 应该如何阅读？
2. 它是一般/正常的表示法吗？

我知道如何使用 D3 功能；这只是我感兴趣的符号。

Answer 1

transition.ease([value[, arguments]]) 的文档似乎相对清楚地说明了他们想要表达的内容。此外，它遵循[] 中具有可选参数的方法的“正常”语法。

在这种情况下，这意味着ease()是transition的一个方法。对于ease() 方法：([value[, arguments]])，表示传递任何参数都是可选的。然后，value[, arguments] 的意思是如果存在value 参数，则可以选择存在无限数量的附加arguments。我说“意图表示”是因为通常能够使用椭圆... 来表示参数的倍数。因此，这通常是：value[, arguments...]。通过进一步查看文档，很明显这是预期的结果。

解析文档（我的附加格式）：

指定转换easing function。

如果value是一个函数，它用来缓和当前参数时序值t，通常在[0,1]范围内。 （在过渡结束时，t 可能略大于 1。）

您可以将函数作为参数传递给transition.ease()。如果这样做，则将其用作确定转换如何发生的函数。

否则，value 被假定为一个字符串，并将参数传递给d3.ease 方法以生成缓动函数。默认的缓动函数是“cubic-in-out”。请注意，无法为每个元素或每个属性自定义缓动函数；但是，如果您使用“线性”缓动函数，则可以使用attrTween 或styleTween 在插值器内应用自定义缓动。

如果value 不是函数，则假定您将使用d3.ease() 作为转换函数。在这种情况下，transition.ease() 的所有参数都将传递给d3.ease()。 d3.ease() 假定 value（在 d3.ease() 的文章中称为 type）是一个字符串。 d3.ease(type[, arguments…]) 能够接受额外的可选参数。为了让您为d3.ease() 函数指定您希望的任何其他参数，transition.ease() 还可以接受这些参数并将它们传递给d3.ease()。

注意：观察transition.ease() 和d3.ease() 之间的交互，我们发现transition.ease([value[, arguments]]) 确实应该用椭圆写成transition.ease([value[, arguments..]])。如果这不是预期用途，那么所描述的与d3.ease() 的交互将没有意义。

如果未指定 ease，则返回绑定到过渡中第一个非空元素的缓动函数。

这实际上并不清楚。我希望它包含一个错误，即“ease”应该是“value”。在这种情况下，它将显示为：

如果未指定 value，则返回绑定到过渡中第一个非空元素的缓动函数。

如果这确实是预期的，那么不为transition.ease() 指定任何参数将导致作为返回值返回绑定到过渡中第一个非空元素的缓动函数。这将是不向此类函数提供任何参数的正常和预期用途。因此，我认为这个问题很可能确实是文档中的错误。这可以通过查看源代码或通过实验来验证。

Answer 2

这意味着value 和arguments 是可选的。