[cairo] cairo_set_user_data () and other "set_user_data" functions

[Michael Urman]

On Fri, Aug 20, 2010 at 18:26, Daniel Goldman <dagoldman at yahoo.com> wrote:
> 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.

While this is key, it's not easy to do. There are lots of patterns you
see across many libraries. When someone who knows the pattern is
writing the code and the documentation, it is easy to forget that the
name of the pattern may not be enough to help someone who hasn't seen
it before. It's also difficult to come up with ways to describe it
that do not seem particularly redundant.

For this case, it sounds like a higher level description of how one
might use "user data" would be useful, and should probably be
referenced (rather than necessarily incorporated) at the API reference
level. My recommendation is to keep asking questions, and keep a thick
skin when those that are used to the idiom are incredulous that anyone
would ask. Then propose doc or tutorial updates, or write it up in a
blog somewhere. :)

-- 
Michael