JavaScript API文档 - functionName([value[, arguments]])符号是什么意思？

Question

这个问题与如何阅读新手API文档？有关。然而，那个问题没有涵盖我在这里提出的特定格式，其中有嵌套的括号（例如，[value[, args]]）。

虽然我认为这可能与任何API相关，但我正在查看D3.js API，具体来说是transition.ease()。我无法理解以下内容的含义：

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

很难找到答案，因为我不知道应该用什么搜索词在谷歌上搜索！我只是想知道：

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

我知道如何使用那个D3函数；我只对符号表示法感兴趣。

- Drenai

---

可能值是可选的，如果提供了值，则参数是可选的。 - Daniel A. White

@georg 不认为这是重复的，因为我在询问一个非常特定的符号 [x[,x]]，而那个重复的问题/答案并没有涵盖到它。下面Mayken的回答涵盖了这个问题。 - Drenai

我同意，虽然紧密相关，但作为重复链接的问题并没有涵盖嵌套可选参数的具体情况。那个问题中得票最高的答案很好地解释了选项符号。虽然这个问题是那个符号的扩展，但显然你和其他人并不觉得它直观。一个好主意是[编辑]这个问题，链接到那个问题，并描述为什么/如何“答案并没有完全回答你的问题”。毕竟，关于重复问题的文本指出，如果是这种情况，则应该提出另一个问题（例如，这个问题）。 - Makyen

如果您在问题中包含这样一个链接和文本，并解释为什么这不是重复的，我会投票重新打开这个问题。 - Makyen

Answer 1

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

在这种情况下，它意味着ease()是transition的一个方法。对于ease()方法：([value[, arguments]])，意味着传递任何参数都是可选的。然后，value[, arguments]旨在表示如果存在value参数，则可以选择存在无限数量的附加arguments。我说“旨在表示”，因为通常使用省略号...来表示能够拥有多个参数。因此，通常会写成：value[, arguments...]。从进一步查看文档中，可以清楚地看出这就是所期望的。

解析文档（由我进行了额外的格式化）：

指定过渡缓动函数。

如果value是一个函数，则用于缓解当前参数化时间值t，通常在范围[0,1]内。(在过渡结束时，t可能略大于1。)

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

否则，假设value是一个字符串，并将参数传递给d3.ease方法以生成缓动函数。默认的缓动函数是“cubic-in-out”。请注意，不可能对每个元素或属性自定义缓动函数；但是，如果使用“linear”缓动函数，您可以在插值器中使用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()将导致返回与转换中第一个非空元素绑定的缓动函数。这将是未提供任何参数给此类函数的正常和预期用法。因此，我认为文档中的这个问题很可能是一个错误。可以通过查看源代码或实验来验证这一点。

- Makyen

---

谢谢。这是一个很好的解释。我相当确定仅基于[value[,params]]，无法知道需要什么。仅凭那个符号，你无法推断出如果value不是一个函数，它期望一个字符串。我以为这是编写API文档的通用方式，但事实并非如此。 - Drenai

Answer 2

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

- Del Ros