[cairo] make return buffers more obvious

[Bryce Harrington]

On Fri, Dec 18, 2015 at 07:39:55PM +0100, Enrico Weigelt, metux IT consult wrote:
> On 18.12.2015 19:29, Bill Spitzak wrote:
> > Can const be used? Perhaps with a "#define const /*nothing*/" on
> > compilers that don't actually support it?
> 
> Const is already used in many places, but we still have to look
> more carefully than just the const modifier.
> 
> Im thinking of somthing like name prefixes, etc.

Well, unfortunately for anything that's in the API, renaming is either
impossible or inconvenient.  Even just adding const to some params is
going to be problematic.  The API docs are probably the best thing to
focus on here.

For internal bits, I would think most of us looking at that code should
be adequately clued in by 'const', and I concur with others that it'd be
worth looking at doing more consistently where it won't break anything
important.

However, my past experience in const-ifying large existing codebases is
that it gets to be a bit like pulling a loose yarn from a sweater...
a seemingly simple const can end up forcing large codebase-wide changes
and it gets out of control pretty quick.  But maybe if you start with
just the very low lying bits it'll be feasible.

Maybe one of the big challenges will be functions that end up calling
into Pixman, as its API is not const safe.

> We also lots of functions which fill out / initialize some structures,
> kind of constructors. I'd suggest those functions should always have
> that return buffer pointer as the first parameter (some already have)

+1 to improving consistency of naming syntax and parameter conventions.
Just be aware that a lot of things are named/structured the way they are
for reasons that are either good or historical, so at least in core bits
tread carefully...  In backend code or other peripheral bits there's
going to be a lot more flexibility.

If there's any constructor-type *_init or *_create routines that don't
follow the return-buffer-first convention, and that aren't themselves
external API, particularly in backend code, they might be worth looking
at improving.

Bryce

> --mtx
> 
> --
> Enrico Weigelt,
> metux IT consulting
> +49-151-27565287
> -- 
> cairo mailing list
> cairo at cairographics.org
> http://lists.cairographics.org/mailman/listinfo/cairo