How to interpret function parameters in software and language documentation?

API 文档中是否有解释函数接口语法的标准? 如果有，是如何定义的？

下面是一个关于如何更改项目颜色的例子，这是用于 Photoshop 的 JavaScript 脚本指南中的“ fill Color”函数:

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

括号的意思是什么? 为什么括号里有逗号？这与下面的示例调用有什么关系？

myPath.fillPath(myNewColor)


myPath.fillPath(mynewColor, {
mode: RGB,
opacity: .5
})
26387 次浏览
小开

括号表示该属性是可选的。但是要注意，如果你想在 nTh 级设置一些属性，你必须要么声明前一个属性，要么声明它们为未定义的:

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

API docs for dynamically typed languages can be not very meaningful if not written carefully, so do not feel too bad about it, even the most seasoned developer can have a hard time trying to understand them.

关于括号之类的东西，通常会有一个代码约定部分来解释字面示例之外的确切用法; 尽管 EBNF、 正方糖和 Railroad Diagrams几乎无处不在，所以你应该熟悉它们以理解大多数符号。

小开
最佳答案

那么，为什么 API 文档的编写方式会让像我这样的常年新手/黑客/DIY 者感到困惑呢？

It's really not meant to be written that way. I'll agree there seems to be no ease of use across API documentations. However, there is a lot of cross over from older man style syntax conventions, to the modern API/namespace conventions.

一般来说，从事 API 工作的人员都有一定的开发背景，或者至少是“高级用户”。这些类型的用户已经习惯了这样的语法约定，API 文档遵循这些约定比尝试创建新的约定更有意义。

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

There really is no standard, or RFC, supersekretsyntaxdoc laying around anywhere, however there is a ~30 year old file for UNIX 手册页综述格式 which is widespread use.

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

带下划线的单词被认为是文字，它们在出现时就被输入。

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

椭圆... 用来表示以前的论证原型可以重复。

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

几乎所有与编程相关的文档都使用这种类型的语法约定，如 巨蟒、 手册、 javascript 库(Highcharts)等。

从 AdobeAPI 分解示例

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

We see that fillPath() (a function) takes optional arguments fillColor, mode, opacity, preserveTransparency, feathe, wholePath or antiAlias. Calling fillPath(), you could pass anywhere from none, to all, of those parameters to it. The commas within the optional [] mean that if this parameter is used in addition to others, you need the comma to seperate it. (Common sense sometimes, for sure, but sometimes some languages like VB, explicitly need those commas to properly delineate which parameter is missing!). Since you did not link to the documentation (and I can't find it on Adobe 的脚本页面) there really is not a way to know which format the Adobe API is expecting. However, there should be an explanation at the top of 大部分 documentation explaining the conventions used within.

因此，这个函数可以有很多用途:

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

Again, there usually are some standards across all documentations relating to API/programming. However in each doc, there could be subtle differences. As a power user, or developer, you ARE expected to be able to read and understand the documents/frameworks/libraries you're attempting to use.

小开

前阵子我也有同样的问题，有人指给我看 扩展 Backus-Naur 形式。

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


提交答案