111

是否有标准来解释 API 文档中函数接口的语法，如果有，它是如何定义的？

下面是一个关于如何更改项目颜色的示例 Photoshop JavaScript 脚本指南中的“fillColor”函数：

fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])

括号是什么意思，为什么括号里有逗号？这与以下示例调用有何关系？

myPath.fillPath(myNewColor)

myPath.fillPath(mynewColor, {
    mode: RGB,
    opacity: .5
})
4

4 回答 4

100

那么，为什么 API 文档的编写方式会混淆像我这样的常年新手/黑客/DIYer？

它真的不应该这样写。我同意 API 文档似乎没有易用性。man但是，从旧式语法约定到现代 API/命名空间约定有很多交叉。

通常，使用 API 的人员类型将具有一些开发背景或至少是“高级用户”。这些类型的用户习惯于这样的语法约定，遵循 API 文档比尝试创建新的文档更有意义。

是否有一些神秘的文档告诉人们如何阅读 API 文档？

确实没有标准或 RFC，supersekretsyntaxdoc 存在于任何地方，但是有一个大约 30 年历史的 UNIX手册页概要格式文件，它被广泛使用。

这方面的一些例子（并回答你的问题）是：

带下划线的单词被认为是文字，并且按照它们出现的方式输入。

参数周围的方括号 ( [] ) 表示该参数是可选的。

省略号 ... 用于表明前面的参数原型可以重复。

以减号开头的参数 - 通常被认为是某种标志参数，即使它出现在文件名可能出现的位置。

几乎所有与编程相关的文档都使用这种类型的语法约定，来自Python、man pages、 javascript libs ( Highcharts ) 等。

从 Adob​​e API 分解您的示例

fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])

我们看到fillPath()(a function) 接受可选参数fillColor, mode, opacity, preserveTransparency, feathe, wholePath或antiAlias. 调用fillPath()，您可以将所有这些参数传递给它。可选中的逗号[]表示如果该参数与其他参数一起使用，则需要逗号分隔。（当然，有时常识，但有时像 VB 之类的某些语言明确需要这些逗号来正确描述缺少哪个参数！）。由于您没有链接到文档（而且我在Adob​​e 的脚本页面上找不到它），因此确实没有办法知道 Adob​​e API 所期望的格式。但是，大多数文档的顶部应该有一个解释，解释其中使用的约定。

因此，此功能可能有多种使用方式：

fillPath() //Nothing passed
fillPath(#000000,RGB) // Black, in RGB mode
fillPath(#000000,RGB,50) // Black, in RGB mode, half opacity

//Now it gets tricky, this might ALSO be acceptable:
fillPath(#000000,50) // Black, no mode, half opacity

//OR
fillPath(#000000,,50) // Black, no mode, half opacity

同样，所有与 API/编程相关的文档中通常都有一些标准。但是，在每个文档中，可能存在细微差别。作为高级用户或开发人员，您应该能够阅读和理解您尝试使用的文档/框架/库。

于 2013-01-16T15:39:44.480 回答
6

如果不仔细编写动态类型语言的 API 文档可能不是很有意义，所以不要为此感到难过，即使是最有经验的开发人员也很难理解它们。

关于括号等，通常有一个代码约定部分应该解释文字示例之外的确切用法；虽然EBNF、正则表达式和铁路图几乎无处不在，但您应该熟悉它们才能理解大多数符号。

于 2013-01-16T15:08:44.933 回答
3

括号表示该属性是可选的。请注意，如果您想在 nTh 等级设置一些属性，您必须为领先的属性声明属性或将它们声明为 undefined ：

fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad
于 2012-06-08T13:44:00.660 回答
1

不久前我也有同样的问题，有人向我指出了Extended Backus-Naur Form。

这是有道理的，因为编程可以用来创造潜在的无限结果。该文档无法为每种可能的情况显示示例。一个很好的常用示例，我很有帮助，但是一旦您可以阅读底层语法，您就可以创建自己的代码。

于 2015-01-04T18:38:31.743 回答