那么,为什么 API 文档的编写方式会混淆像我这样的常年新手/黑客/DIYer?
它真的不应该这样写。我同意 API 文档似乎没有易用性。man
但是,从旧式语法约定到现代 API/命名空间约定有很多交叉。
通常,使用 API 的人员类型将具有一些开发背景或至少是“高级用户”。这些类型的用户习惯于这样的语法约定,遵循 API 文档比尝试创建新的文档更有意义。
是否有一些神秘的文档告诉人们如何阅读 API 文档?
确实没有标准或 RFC,supersekretsyntaxdoc 存在于任何地方,但是有一个大约 30 年历史的 UNIX手册页概要格式文件,它被广泛使用。
这方面的一些例子(并回答你的问题)是:
带下划线的单词被认为是文字,并且按照它们出现的方式输入。
参数周围的方括号 ( [] ) 表示该参数是可选的。
省略号 ... 用于表明前面的参数原型可以重复。
以减号开头的参数 - 通常被认为是某种标志参数,即使它出现在文件名可能出现的位置。
几乎所有与编程相关的文档都使用这种类型的语法约定,来自Python、man pages、 javascript libs ( Highcharts ) 等。
从 Adobe API 分解您的示例
fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])
我们看到fillPath()
(a function) 接受可选参数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/编程相关的文档中通常都有一些标准。但是,在每个文档中,可能存在细微差别。作为高级用户或开发人员,您应该能够阅读和理解您尝试使用的文档/框架/库。