[cairo] make return buffers more obvious

[Bryce Harrington]

On Fri, Dec 18, 2015 at 09:23:13PM +0100, Enrico Weigelt, metux IT consult wrote:
> On 18.12.2015 20:43, Bill Spitzak wrote:
> 
> > I doubt it, but I could not understand why const is not being used or
> > why the original poster asked this question.
> 
> That's only part of my point. I'd like to know (from the function
> prototype / naming convention / inline-description) which parameters
> are accessed in which way (eg. changed).
> 
> We can't use const everywhere for that. For example, we're filling
> some structure with pointers to other objects. Further suppose that
> structure has non-const poiners, because somewhere, somewhen, we'd
> like to change the object our passed pointer points to (but not in
> that function itself).
> 
> const simply can't express that (actually, I dont know any language
> that can do that), so we'd need another way of describing this.
> 
> And there're other aspects, eg. whether some structs need some
> cleanups (destructors), not-null constraints, etc, etc.

I'd definitely strongly support inline-description document fixes for
these kinds of things.

For construction/destruction, ref/deref counters, locking, fencing, and
a few other standard fundamental operations, naming convention
standardization makes sense.  And const'ing internal bits might be ok
too, like I commented in the other email.

Beyond that though, there are so many myriad ways that parameters can be
used in functions I'm skeptical that we should try to enforce anything
through the prototype, and I think docs are the right way to go.

If there ever is a Cairo 2.0, though, I'd definitely like to see a
stronger function naming consistency.

Bryce