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

Question

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

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

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

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

myPath.fillPath(myNewColor)

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

Answer 1

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

这确实不应该这样写。我同意 API 文档似乎并不易于使用。然而，从旧的 man 风格语法约定到现代 API/命名空间约定有很多交叉。

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

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

确实没有标准或 RFC、supersekretsyntaxdoc 存在于任何地方，但是有一个大约 30 年前的 UNIX 文件 man page synposis format这是广泛使用的。

这方面的一些例子(并回答你的问题)是:

Underlined words are considered literals, and are typed just as they appear.

Square brackets ( [] ) around an argument indicate that the argument is optional.

Ellipses ... are used to show that the previous argument-prototype may be repeated.

An argument beginning with a minus sign - is often taken to mean some sort of flag argument even if it appears in a position where a file name could appear.

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

<小时/>

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

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

我们看到 fillPath() (一个函数)采用可选参数 fillColor、mode、opacity、preserveTransparency、feathe、wholePath 或 antiAlias。调用fillPath()，您可以将这些参数传递给任何地方，从无参数到全部参数。可选 [] 中的逗号表示，如果除了其他参数之外还使用此参数，则需要逗号分隔它。 (当然，有时是常识，但有时某些语言(例如 VB)明确需要这些逗号来正确描述缺少哪个参数!)。由于您没有链接到文档(并且我在 Adobe's scripting page 上找不到它)，因此确实没有办法知道 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/编程相关的所有文档通常都有一些标准。然而，在每个文档中，可能存在细微的差异。作为高级用户或开发人员，您应该能够阅读和理解您尝试使用的文档/框架/库。