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

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

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


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

myPath.fillPath(myNewColor)

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

最佳答案

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

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

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

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

真的没有标准或RFC,supersekretsyntaxdoc随处可见,但是UNIX man page synposis format已有30多年的历史了,文件被广泛使用。

一些示例(并回答您的问题)将是:


  带下划线的单词被视为文字,并按其出现的形式键入。
  
  参数周围的方括号([])表示该参数是可选的。
  
  省略号...用于表示可以重复前面的参数原型。
  
  以减号开头的参数-即使出现在可能出现文件名的位置,也通常被认为是某种标志参数。


几乎所有与编程相关的文档都使用这种类型的语法约定,例如Pythonman pages,javascript库(Highcharts)等。



从Adobe API分解您的示例

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


我们看到fillPath()(一个函数)带有可选参数fillColor, mode, opacity, preserveTransparency, feathe, wholePathantiAlias。调用fillPath(),您可以将这些参数从任何地方传递到所有地方。可选[]中的逗号表示如果除其他参数之外还使用此参数,则需要用逗号分隔。 (可以肯定,常识,但有时某些语言,例如VB,明确需要那些逗号来正确地描述缺少哪个参数!)。由于您没有链接到文档(并且在Adobe's scripting page上找不到),因此实际上没有办法知道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 /编程有关的文档中通常都有一些标准。但是在每个文档中,可能会有细微的差异。作为高级用户或开发人员,您应该能够阅读和理解您尝试使用的文档/框架/库。

关于api - 如何解释API文档功能参数?,我们在Stack Overflow上找到一个类似的问题:https://stackoverflow.com/questions/52534627/

10-10 18:37
查看更多