如何解释软件和语言文档中的函数参数？

Question

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

以下是Photoshop JavaScript脚本指南中“fillColor”函数更改项目颜色的示例：

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

方括号的含义是什么，为什么方括号中有逗号？这与以下示例调用有何关系？

myPath.fillPath(myNewColor)

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

- dbonneville

---

API参考文档中是否有介绍它们语法约定的简介？ - Greg Hewgill

对于投票关闭的人：我认为这个问题是有价值的，如果可以的话，我会“投票不关闭”。这不是我以前见过（或听说过）的问题，它涉及到一个合法的编程相关问题，当我教授编程相关知识时，我个人会发现答案很有用。 - David Wolever

我觉得您错过了原始帖子中的一个粗体句子。如果您在Google上搜索“如何阅读API文档”，前10个结果中的信息会提到“抽象”、“不完整”、“混乱”等内容，这进一步强调了我的问题。 - dbonneville

Greg：Photoshop/Adobe产品没有介绍。它们都遵循每个产品2个PDF的相同格式。我想到的其他API也是如此。在许多情况下，有一种隐含的知识，我并不具备，但我肯定希望拥有。 - dbonneville

一个有用的资源是内置在Extendscript IDE中的对象查看器（按F1键）。单击对象将显示其具有的属性和方法。此外，如果它使用其他对象作为参数，它（通常）会链接到它们，以便您可以查看它们具有的属性。它不是完美的，但它很有帮助。 - pdizz

一些常见语法约定的Linux/Unix手册页相关问题。 - Eric Postpischil

Answer 1

那么为什么API文档会以一种使像我这样的永久新手/黑客/DIYer感到困惑的方式编写呢？

实际上并不是要以这种方式编写。我同意在API文档中似乎没有任何易用性。然而，从旧有的man风格语法约定到现代API/命名空间约定有很多交叉点。

通常，使用API的人都具有开发背景或至少是“高级用户”。这些类型的用户已经习惯了这种语法约定，所以在API文档中遵循这些约定比尝试创建新的约定更有意义。

是否存在某个神秘的文档可以告诉人们如何阅读API文档？

实际上并没有标准或RFC，也没有超级秘密的语法文档，但是有一个大约30年历史的UNIX文件man page synposis format广泛使用。

以下是一些示例（回答您的问题）：

下划线的字词被视为字面值，应该按照它们的原样输入。 方括号（[]）将参数括起来表示该参数是可选的。 省略号（...）用于显示先前的参数原型可能重复出现。 以减号（-）开头的参数通常被视为某种标志参数，即使它出现在文件名可能出现的位置。 几乎所有与编程有关的文档都使用这种类型的语法约定，例如 Python、man pages、JavaScript库（Highcharts）。

---

从Adobe API中分解您的示例

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

我们看到fillPath()（一个函数）有可选参数fillColor，mode，opacity，preserveTransparency，feathe，wholePath或antiAlias。当调用fillPath()时，你可以向它传递从零个到所有这些参数中的任意数量。在可选[]中的逗号表示如果该参数与其他参数一起使用，则需要逗号将它们分隔开来（有些语言例如VB，明确需要这些逗号以正确地区分缺少哪个参数！）。由于你没有链接到文档（我在 Adobe脚本页面上也找不到它），因此真的没有办法知道Adobe 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/编程的所有文档通常都有一些标准。然而，在每个文档中，可能会存在一些微小的差异。作为高级用户或开发人员，您应该能够阅读和理解您尝试使用的文档、框架和库。

- PenguinCoder

---

UNIX man手册的概要格式连结已经失效，有没有其他连结可以替换？@PenguinCoder 更新：根据Unix Stack Exchange的回答（http://unix.stackexchange.com/questions/17833/understand-synopsis-in-manpage），这种格式松散地基于Extended Backus-Naur Form（EBNF）。 - steviesh

这里有一个关于_man page synposis format_的存档副本。 - CodeManX

Answer 2

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

关于括号等符号，通常会有一个代码规范部分，应该会解释除字面示例外的精确用法; 虽然EBNF、Regex和Railroad Diagrams几乎无处不在，所以你应该熟悉它们以理解大多数符号。

- fortran

Answer 3

方括号表示该属性是可选的。但要注意，如果您想设置第n个排名的某个属性，必须声明前导属性的属性或将它们声明为未定义：

fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad

- Loic Aigon

---

fillPath (mode) 可能没问题。如果可选参数在非可选参数之前出现，通常意味着该函数足够智能，可以检测可选参数是否已给出（例如，通过查看其类型）。 - ThiefMaster

嗯，那是可能的，但我更喜欢依赖于一些强大的东西，而不是脚本可能为我做的事情:D - Loic Aigon

Answer 4

我之前也有同样的问题，有人指向了扩展Backus-Naur范式。

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

- StevenKW