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

[Daniel Goldman]

> >  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
>
I basically agree with what you say. First, in general, it's not easy to write 
good documentation. It's time-consuming. It requires attention to detail, an 
understanding of technical writing, and an understanding of the subject matter. 
And most programmers aren't all that interested in this aspect of writing 
software.

I do think it's better to incorporate most higher level descriptions directly 
into the API reference docs. I think the API docs should have detail more or 
less akin to a man page. They don't right now. They're too terse.

I agree with the redundancy problem you point out. DRY (don't repeat yourself). 
I think that could be resolved by adding more "see also" links, which are 
currently mostly missing from the docs. In other words, the cairo_set_user_data 
() documentation could go into more detail, and the other "set_user_data" 
functions would all link to each other and to cairo_set_user_data ().

I appreciate your advice about keeping a thick skin. If some (or most!) of my 
suggestions go over like a lead balloon, I'll maintain my calm. I understand 
that people have been working on this project for many years, with a lot of 
success, and are used to a certain idiom. If nothing else, my suggestions are in 
this archive, which serves as additional documentation.

Daniel