如何阅读newbs的API文档？

Question

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

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

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

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

当我读到这篇文章时,乍一看毫无意义.为什么有括号,我怎么知道我不应该在实现中使用它们？为什么括号中有逗号？我知道从我找到的样本代码应该是什么样的,这是:

myPath.fillPath(myNewColor)

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

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

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

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

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

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

Answer 1

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

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

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

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

实际上没有任何标准或RFC,supersekretsyntaxdoc存在于任何地方,但是有一个大约30年的UNIX 手册页synposis格式的文件,这是广泛使用的.

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

带下划线的单词被视为文字,并且就像它们出现时一样输入.

参数周围的方括号([])表示该参数是可选的.

省略号......用于表示可以重复前一个参数原型.

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

几乎所有与编程相关的文档都使用这种语法约定,包括Python,手册页,javascript库(Highcharts)等.

从Adobe API中分解您的示例

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

我们看到fillPath()(一个函数)接受可选参数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 /编程相关的所有文档中通常都有一些标准.但是在每个文档中,都可能存在细微差别.作为高级用户或开发人员,您需要能够阅读和理解您尝试使用的文档/框架/库.

Answer 2

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

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