API Lacking Consistant Code Examples

Hi All,
As an experienced programmer I find that the Blender API is lacking in code examples. Often I know what I want to do with the API, but I just can’t find an example of the syntax.

http://www.blender.org/documentation/245PythonDoc/API_intro-module.html
http://www.blender.org/documentation/245PythonDoc/trees.html

Generally an API function has Parameters and Returns specified, but it does not have Usage specified. Seems like this is a gaping omission by the documentors. Shouldn’t there be a requirement that documentors supply Usage as well as Parameter and Returns?

For instance:
http://www.blender.org/documentation/245PythonDoc/Image-module.html

I can go to this link and see some example code. (yeah!)

But as I dig a little deeper to the function I need.
http://www.blender.org/documentation/245PythonDoc/Image.Image-class.html#getPixelI

I am left high and dry on how to operate or extract my RGBA values. I know what RGBA is. I know I have chosen this routine because I want the 0-255 values. But how do I get my red value from the list that is returned? And this is only one example. Multiply that by the number of functions I am trying to use and a wall suddenly appears. I think it is this wall that leads us to the forum to ask for help.

I know this is open source software and persons at different levels of understanding are contributing. But I am asking the person that already knows a little more to put that extra piece of code into the documentation for beginers.

Are you experienced with Python or another language?

The returns section generally is enough for somebody with python knowledge to figure out how to use something. For instance, to get the red value out you would just do something like:


myColors = getPixelI(x,y)
red = myColors[0]

Since we know that it returns a list, we know how to use it, essentially. This is the same with many functions.

In my opinion, providing examples is a sure fire way to get more people to come here complaining about why certain pieces of code given in the examples and then copy/pasted into their own code don’t work. You have to work with the API and learn its quirks to master it. Beyond that, supplying example code for the hundreds (thousands?) of functions in the API is hard work, especially when many are similar in usage and finding one function’s usage gives you another function’s usage. It would require immense amounts of time to define the explicit usage of functions. Its much easier, and much better for the programmer from a learning standpoint, to put the implicit usage, from the returns and parameters, and then cause the programmer (beginner or not) to translate that to explicit usage in their code.