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 :
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.
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
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’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
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.