Question

我正在阅读Photoshop，Illustrator和InDesign的JavaScript脚本指南。 API真的很难读，因为它假设我知道某些简写约定。问题不仅限于此特定脚本指南。我可以列出几十个出现同样问题的人。

当我将API视为一天24小时不在代码中的人时，我想查看一些内容，并以最基本的形式查看代码的简单示例。但通常一开始就不容易理解它。

这是一个例子。我正在查找如何在Photoshop中通过JavaScript更改项目的颜色。所以我搜索PDF并找到“fillColor”。我在文档中找到了这个：

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

当我读到这篇文章时，乍一看没有任何意义。为什么有括号，我怎么知道我不应该在实现中使用它们？为什么括号中有逗号？我知道代码应该从我找到的样本中看起来是什么样的，这就是：

myPath.fillPath(myNewColor)

如果我没有看到这个例子，我绝不会从API代码中看出这个方法在实现时的外观。其他人指出这个方法的扩展示例可能如下所示：

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

行。我看到我可以省略隐含的可选参数。精细。但同样，我绝不会从API中猜到这一点。

那么，是否有一些神秘的文件告诉人们如何阅读API文档？为什么这样写？我有什么先验知识？为什么会这样，我该怎么做才能停止对它的疑惑并“得到”它，所以我可以更乐意阅读并实现下一个API？

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

Answer 1

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

这真的不是那样写的。我同意在API文档中似乎没有易用性。但是，从旧的man样式语法约定到现代API /命名空间约定有很多交叉。

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

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

实际上没有任何标准或RFC，supersekretsyntaxdoc存在于任何地方，但是有一个约30年历史的UNIX man page synposis format文件被广泛使用。

这方面的一些例子（并回答你的问题）将是：

带下划线的单词被视为文字，并按其显示的方式键入。

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

Ellipses ...用于表示可以重复上一个参数原型。

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

几乎所有与编程相关的文档都使用此类语法约定，来自Python，man pages，javascript libs（Highcharts）等。

从Adobe API中分解您的示例

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

我们看到fillPath()（一个函数）使用可选参数fillColor, mode, opacity, preserveTransparency, feathe, wholePath或antiAlias。调用fillPath()，您可以从任何地方传递到所有这些参数。可选[]中的逗号表示如果除了其他参数之外还使用此参数，则需要使用逗号分隔它。（有时候常识，但有时候某些语言如VB，明确需要这些逗号来正确描述缺少哪个参数！）。由于您没有链接到文档（我在Adobe's scripting page上找不到它），因此确实无法知道Adobe API期望的格式。但是， most 文档的顶部应该有一个解释，解释其中使用的约定。

所以，这个功能可能会用很多种方式：

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 /编程相关的文档都有一些标准。但是在每个文档中，都可能存在细微差别。作为高级用户或开发人员，您需要能够阅读和理解您尝试使用的文档/框架/库。

Answer 2

如果不仔细编写动态类型语言的API文档可能没有多大意义，所以不要觉得太糟糕，即使是经验最丰富的开发人员也很难理解它们。

关于括号等，通常有一个代码约定部分，应该解释文字示例之外的确切用法;虽然EBNF，Regex和Railroad Diagrams几乎无处不在，但您应该熟悉它们以理解大多数注释。

Answer 3

括号表示该属性是可选的。请注意，如果要在nTh等级设置soem属性，则必须为eading属性声明属性或将它们声明为undefined：

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

卢瓦克 http://www.loicaigon.com

Answer 4

有一段时间我有同样的问题，有人指着我Extended Backus–Naur Form。

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

如何阅读newbs的API文档？

4 个答案: