Is there a standard to interpret the syntax of function interfaces in API documentations and if yes, how is it defined?
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
})
Best Answer
So why is API documentation written in such a way as to confuse perennial newbs / hackers / DIYers like myself?
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.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.
Is there some mysterious document somewhere that tells people how to read API documentation?
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 :
Almost all programming related documentation uses this type of syntax convention, from Python, man pages, javascript libs (Highcharts), etc.
Breaking down your example from Adobe API
We see that
fillPath()
(a function) takes optional argumentsfillColor, mode, opacity, preserveTransparency, feathe, wholePath
orantiAlias
. CallingfillPath()
, 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 :
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.