如何读取新的API文档？

Question

我正在阅读Photoshop、IlluStrator和InDesign的JavaScript脚本指南。这个API真的很难读，因为它假设我知道某些速记约定。问题并不局限于这个特定的脚本指南。我可以列举出几十个同样的问题。

当我每天24小时不使用代码时，我想要查找一些内容，并以最基本的形式查看代码的简单示例。但通常一开始很难理解。

下面是一个例子。我正在查看如何在Photoshop中用JavaScript更改项目的颜色。所以我搜索PDF并找到“填充颜色”。我在文档里找到了这个：

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

当我读到这篇文章时，乍一看是毫无意义的。为什么有方括号，我怎么知道我不应该在实现中使用它们？为什么括号里有逗号？我知道密码是什么应从我找到的样本看，如下所示：

myPath.fillPath(myNewColor)

如果我没有看过这个例子，我就永远不会从API代码中推测出这个方法在实现时的样子。还有人指出，此方法的扩展示例可能如下所示：

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

好的。我可以省略隐含的可选参数。很好。但是，我从来不会从API中猜到这一点。

所以,有什么神秘的文档告诉人们如何阅读API文档吗？为什么写成这样？假设我有什么先验知识？为什么它是这样的，我能做什么来停止对它的怀疑并“得到”它，这样我就可以更愉快地阅读和实现下一个API了？

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

如何读取新的API文档？

Answer 1

如果不仔细编写用于动态类型化语言的API文档可能不是很有意义，所以不要为此感到太糟糕，即使是最有经验的开发人员也很难理解它们。关于括号之类的内容，通常有一个代码约定部分，它应该解释文字示例之外的确切用法；EBNF, 雷杰克斯和铁路图几乎无所不在，所以你应该熟悉它们来理解大多数符号。