[cairo] a friendly suggestion to the developers

[M.R.]

 > A fair amount of the
> cairo API reference docs similarly kind of misses the boat. Even if the missing
> content were found in tutorials (it's mostly not), it should not be left out of
> the API docs. Good, useful API docs explain more about the intention and
> usefulness of functions, like the great examples you've provided. Good docs
> don't just tersely repeat the names of self-explanatory function and parameter
> names.

Good API documents are always "two-tier": the first tier is an easy to
navigate (and yes, terse, possibly even terser than Cairo's  reference
manual is) "function/object inventory". However, the "second tier" is
much, much more. (the two might or might not be rolled up in a single
"book"). In our case, that second tier would provide a short,
descriptive paraghaph of what you call "intentions" (and I might call
"the statement of purpose" and a complete set of rules that arguments
must conform to, and an equally complete set of rules that the invoker
must follow once the function returns: for instance, is the application
supposed to call cairo_surface_destroy() on a surface created by
cairo_image_surface_create() which returned "nil" surface? If the
words were "...and should always call cairo_surface_destroy() when 
done..." instead of just "...and should call cairo_surface_destroy()..."
I wouldn't be left wondering.

The craft of writing good documentation is much less common and thus
much more valuable than the craft of writing good code. Whatever
benefits open source brought us, one thing it took away: the quality
of documentation. If I have one advice to the creators of open source
programming libraries it is this: when it comes to documentation,
simply *assume you are writing a closed source library!* Not only
will the programmers that use the library be better off, you and
those that will inherit your code will be better off.

Instructing the user of your product to consult the source
is not only a sign of impotence and lack of that craft; it is a
particularly dangerous advice to give to a novice that lacks the 
experience required to distinguish between those instances where
the knowledge obtained by looking at the source is illuminating,
and those where it is dangerous. So whenever you point the user to the 
source, you potentially paint in a corner someone who'll have to
maintain your code when a bug is discovered or a better implementation
is indicated.

With a couple of minor gripes (first and foremost would be the ability
of an application to control the world-to-device coordinate pipeline all 
the way to the integer pixel coordinate if it so chooses!) Cairo
is one of the best (if not *the* best) graphical libraries I used
(and I used a few...) but the documentation is, well, of the typical 
"use the source, Luke" variety. At this point, adding to the quality
of documentation is likely to give the project greater pay-back than
adding to the functionality.

Marko R.