如何解释API文档中的函数参数？

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

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

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

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

myPath.fillPath(myNewColor)

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

---

括号表示该属性是可选的。请注意，如果要将某些属性设置为第n个级别，则必须声明前导级别的属性或将其声明为未定义：

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

---

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

---

关于方括号之类的东西，通常会有一个代码约定部分来解释文字示例之外的确切用法；虽然，和几乎无处不在，所以您应该熟悉它们以了解大多数符号。

那么为什么API文档的编写方式会让我这样的常年新手/黑客/DIYER感到困惑呢？

它真的不应该这样写。我同意API文档中似乎没有易用性。然而，从较旧的

man

风格的语法约定到现代的API/名称空间约定有很多交叉

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

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

实际上，任何地方都没有标准的，或RFC，supersekretsyntaxdoc，但是有一个大约30年前的UNIX文件被广泛使用

这方面的一些例子（以及回答您的问题）是：

带下划线的单词被视为文字，并按其外观键入

参数周围的方括号（[]）表示该参数是可选的

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

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

几乎所有与编程相关的文档都使用这种语法约定，例如，from、javascript libs（）等

---

从AdobeAPI分解您的示例

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

我们看到，

fillPath（）

（一个函数）采用可选参数

fillColor、mode、opacity、preserveTransparency、feathe、wholePath

或

antiAlias

。调用

fillPath（）

，您可以将这些参数中的任何一个传递给它。可选的

[]

中的逗号表示，如果此参数与其他参数一起使用，则需要用逗号将其分隔开。（当然，有时是常识性的，但有时像VB这样的一些语言明确需要这些逗号来正确描述缺少的参数！）。由于您没有链接到文档（我在上面找不到），因此无法知道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/编程相关的文档中都有一些标准。然而，在每个文档中，都可能存在细微的差异。作为超级用户或开发人员，您应该能够阅读和理解您试图使用的文档/框架/库。

不久前，我也有同样的问题，有人向我指出

---

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

有没有介绍描述其语法约定的API参考文档？对于投票结束的人：我相信这个问题有价值，如果可以，我会“投票不结束”。这不是我以前见过（或听到过）的问题，它解决了一个与编程相关的合法问题，我个人认为，当我教人们编程相关的东西时，答案会很有用。德里克：我想你错过了原始帖子中的一句粗体句子。如果你在谷歌上搜索“如何阅读api文档”，前10个结果中的信息会说“抽象”、“不完整”、“混乱”等，从而强化了我的问题。格雷格：Photoshop/Adobe产品没有介绍。它们都遵循相同的格式，每个产品有2个PDF。我正在考虑的其他API也是这样做的。有一个隐含的知识，我在很多情况下都不知道，当然也希望知道。一个有用的资源是Extendscript IDE中内置的对象查看器（点击F1）。单击一个对象将显示它的属性和方法。此外，如果它使用其他对象作为参数，它（通常）会链接到它们，以便您可以看到它们也具有哪些属性。它不是完美的，但有帮助。

fillPath（mode）

可能还可以。如果可选参数出现在非可选参数之前，这通常意味着函数足够聪明，可以检测是否给出了可选参数（例如，通过查看其类型）嗯，这是可能的，但我更喜欢依靠一些强大的东西，而不是脚本可能为我做的事情：DUNIX手册页概要格式链接已经死了——有人有替代链接吗@企鹅编码器更新：基于[（Unix S）