API文档函数参数如何解读? [英] How to interpret API documentation function parameters?

问题描述

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

Is there a standard to interpret the syntax of function interfaces in API documentations and if yes, how is it defined?

以下是关于如何更改项目颜色的示例，适用于 Photoshop 的 JavaScript 脚本指南，用于fillColor"功能:

Here is an example on how to change the color of an item the JavaScript scripting guide for Photoshop for the "fillColor" function:

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

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

What is the meaning of the brackets and why are there commas in the brackets? How does this relate to the following example calls?

myPath.fillPath(myNewColor)

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

推荐答案

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

它真的不应该这样写.我同意 API 文档似乎没有易用性.然而，从旧的 man 风格的语法约定到现代 API/命名空间约定有很多交叉.

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 文档比尝试创建新文档更有意义.

Typically, the type of person who works with API, will have some background in development or at the least a 'power user'. These types of users are used to such syntax conventions and it makes more sense for the API document to follow than to try to create new ones.

是否有什么神秘的文档告诉人们如何阅读 API 文档?

确实没有任何标准或 RFC、supersekretsyntaxdoc 放置在任何地方，但是有一个大约 30 年的 UNIX 文件 使用广泛的手册页概要格式.

There really is no standard, or RFC, supersekretsyntaxdoc laying around anywhere, however there is a ~30 year old file for UNIX man page synposis format which is widespread use.

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

Some examples of this (and answering your question) would be :

带下划线的字词被视为文字，按其出现的形式输入.

Underlined words are considered literals, and are typed just as they appear.

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

Square brackets ( [] ) around an argument indicate that the argument is optional.

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

Ellipses ... are used to show that the previous argument-prototype may be repeated.

以减号开头的参数 - 通常表示某种标志参数，即使它出现在可能出现文件名的位置.

An argument beginning with a minus sign - is often taken to mean some sort of flag argument even if it appears in a position where a file name could appear.

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

Almost all programming related documentation uses this type of syntax convention, from Python, man pages, javascript libs (Highcharts), etc.

从 Adob​​e API 中分解您的示例

Breaking down your example from Adobe API

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

我们看到 fillPath()(一个函数)接受可选参数 fillColor、mode、opacity、preserveTransparency、feathe、wholePath 或 antiAlias.调用 fillPath()，您可以向它传递从无到所有这些参数的任何位置.可选的[] 中的逗号表示，如果该参数与其他参数一起使用，则需要用逗号将其隔开.(有时是常识，当然，但有时像 VB 这样的一些语言，明确需要这些逗号来正确描述缺少哪个参数！).由于您没有链接到文档(而且我在 Adobe 的脚本页面) 确实没有办法知道 Adob​​e API 期望哪种格式.但是，大多数文档的顶部应该有一个解释，解释其中使用的约定.

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's scripting page) 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 most documentation explaining the conventions used within.

所以，这个函数可能有很多用途:

So, this function could probably be used many ways :

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/编程相关的所有文档通常都有一些标准.然而，在每个文档中，可能会有细微的差异.作为高级用户或开发人员，您应该能够阅读和理解您尝试使用的文档/框架/库.

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.

这篇关于API文档函数参数如何解读?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！