如何解释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放置在任何地方，但是UNIX大约有30年的历史了

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库(

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

从Adobe 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，明确需要那些逗号来正确地描述缺少哪个参数！).由于您未链接到文档(而且我无法在 Adob​​e的脚本页面上找到它)确实没有办法知道Adobe API期望哪种格式.但是， most 文档的顶部应该有一个解释，解释其中使用的约定.

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屋！