[Cairo] format for api docs

[Thomas Hunger]

Hello
> That doesn't really match my experience. The advantage of in-source
> docs is that it makes the most convenient time to update the docs
> the point when you change the code. So, there is no incentive to
> put off the documentation to some other time.

Carl is right, since the gtk-doc inline descriptions would go into cairo.c 
which does nothing but delegating to gstate most of the time,  one would need 
two editor windows,  one for the doc in cairo.c and one where the actual 
functionality is written or updated (e.g. cairo_surface.c).

Also the api is pretty small compared to gtk and not likely (?) to change in 
huge leaps in the near future, so an external documentation should be fine. 
Is it docbook then, or rather html/latex or some other format? 

Tom