如何解释API文档功能参数？

103

API文档中是否存在解释功能接口语法的标准，如果是，则如何定义？

这是有关如何为Photoshop的JavaScript脚本指南针对“ fillColor”功能更改项目颜色的示例：

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

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

myPath.fillPath(myNewColor)

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

api documentation

— 博讷维尔
source

4

API参考文档是否有介绍其语法约定的简介？

— 格雷格（Greg Hewgill）2012年

35

对于投票结束的人：我相信这个问题是有道理的，如果可以的话，我会“投票决定不结束”。这不是我以前见过（或听过）的问题，它解决了一个与编程有关的合法问题，当我向人们传授与编程有关的知识时，我个人会找到有用的答案。

— David Wolever

4

德里克（Derek）：我想您错过了原始帖子中其中一个大胆的句子。如果您用谷歌搜索“如何阅读api文档”，则前10个结果中的信息会显示诸如“抽象”，“不完整”，“令人困惑”之类的内容，从而进一步说明了我的问题。

— dbonneville

2

格雷格：没有介绍Photoshop / Adobe产品。它们每个产品均遵循2个PDF的相同格式。我正在考虑的其他API都执行相同的操作。有一个隐性知识，我在很多情况下都没有，当然也想。

— dbonneville 2012年

1

有用的资源是Extendscript IDE中内置的对象查看器（按F1键）。单击一个对象将向您显示它具有哪些属性和方法。同样，如果它使用其他对象作为参数，它通常也会链接到它们，这样您就可以看到它们也具有哪些属性。这不是完美的，但有帮助。

— pdizz

92

那么，为什么要以这样的方式编写API文档，以使像我这样的常年新手/黑客/ DIY迷惑呢？

确实不是要这样写。我同意所有API文档似乎都不容易使用。但是，从较旧的man样式语法约定到现代的API /命名空间约定，有很多交叉之处。

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

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

真的没有标准或RFC，supersekretsyntaxdoc随处可见，但是有大约30年的UNIX 手册页摘要格式文件已被广泛使用。

一些示例（并回答您的问题）将是：

带下划线的单词被视为文字，并且按照出现的形式键入。

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

省略号...用于表示可以重复前面的参数原型。

以减号开头的参数-即使出现在可能出现文件名的位置，也经常被认为是某种标志参数。

几乎所有与编程相关的文档都使用这种类型的语法约定，例如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 /编程有关的文档中通常都有一些标准。但是在每个文档中，可能会有细微的差异。作为高级用户或开发人员，应该能够阅读和理解您尝试使用的文档/框架/库。

— 企鹅编码器
source

5

UNIX手册页摘要格式链接已失效-有人有替换链接吗？@PenguinCoder更新：根据[ unix.stackexchange.com/questions/17833/...（Unix的堆栈交换），它是松散的基础上[ en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form（EBNF）

— steviejay

有一个归档副本的手册页synposis格式

— CodeManX

5

如果不仔细编写，则用于动态类型语言的API文档可能没有太大的意义，因此不要为此感到难过，即使是经验最丰富的开发人员也很难理解它们。

关于方括号等，通常有一个代码约定部分，应在文字示例之外解释确切的用法；尽管EBNF，正则表达式和铁路图几乎无处不在，所以您应该熟悉它们才能理解大多数符号。

— Fortran
source

3

方括号表示该属性是可选的。但是请注意，如果要在nTh等级上设置某些属性，则必须声明前一个属性或将其声明为undefined：

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

— Loic Aigon
source

2

fillPath (mode)可能还可以。如果可选参数出现在非可选参数之前，则通常意味着该函数足够聪明，可以检测是否给出了可选参数（例如，通过查看其类型）

— ThiefMaster 2012年

1

MMmm很好，这是可能的，但我宁愿依靠强脚本而不是脚本可能为我做的事：D

— Loic Aigon 2012年

1

不久前我也遇到了同样的问题，有人指出我是扩展Backus–Naur形式。

这是有道理的，因为编程可用于创建潜在的无限结果。该文档无法显示每种情况下的示例。一个很好的常用示例，对我很有帮助，但是一旦您阅读了基础语法，便可以创建自己的代码。

— 史蒂文·KW
source