[cairo] cairo_set_user_data () and other "set_user_data" functions
dagoldman at yahoo.com
Sat Aug 21 11:13:26 PDT 2010
> > 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
> > 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. :)
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
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.
More information about the cairo