I'm reading through the JavaScript scripting guide for Photoshop, Illustrator and InDesign. The API is really hard to read because it assumes I know certain shorthand conventions. The problem is not limited to this particular scripting guide. I could list out dozens that present the same problem.
When I read an API as someone that does not live in code 24 hours a day, I want to look something up and see a simple example of the code in action in the most basic form. But often it's not easy to make sense of it at first.
Here is an example. I'm look up how to change the color of an item by JavaScript in Photoshop. So I search the PDF and find "fillColor". I find this in the docs:
fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])
When I read this, it at first glance makes no sense. Why are there brackets and how would I know I'm not supposed to use them in an implementation? Why are commas in the brackets? I know what the code should look like from a sample I found, which is this:
myPath.fillPath(myNewColor)
If I hadn't seen the example, I would NEVER divine from the API code that that is how this method should look when implemented. Someone else pointed out that an extended example for this method might look like this:
myPath.fillPath(mynewColor, {
mode: RGB,
opacity: .5
})
OK. I see I can leave out implied optional parameters. Fine. But again, I NEVER would have guessed this from the API.
So, is there some mysterious document somewhere that tells people how to read API documentation? Why is it written like that? What prior knowledge does it assume I have? Why is it like this, and what can I do to stop wondering about it and "get" it, so I can more happily read and implement the next API?
So why is API documentation written in such a way as to confuse perennial newbs / hackers / DIYers like myself?