How to read API documentation for newbs? [closed]

Question

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?

Answer 1

I had this same question a while back and somebody pointed me to Extended Backus–Naur Form.

It makes sense because programming can be used to create potentially limitless outcomes. The documentation can not display an example for every possible case. A good example of common use I helpful but once you can read the underlying syntax you are able to create your own code.

Answer 2

API docs for dynamically typed languages can be not very meaningful if not written carefully, so do not feel too bad about it, even the most seasoned developer can have a hard time trying to understand them.

About brackets and such, there is usually a code conventions section that should explain the exact usage outside literal examples; although EBNF, Regex and Railroad Diagrams are almost ubiquitous, so you should be familiar with them to understand most notations.

Answer 3

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.

Answer 4

The brackets mean that the property is optional. Be aware though that if you want to set soem property at the nTh rank, you have to either declare properties for the eading one or declare them as undefined :

fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad

Loic http://www.loicaigon.com