[cairo] surfaces and backends

[Dominic Lachowicz]

> OK, so if I'm a user reading this, where can I learn the correct value
> to compare against? Just guessing based on the example and asking the
> compiler, or grubbing through header files are not good answers. The
> correct answer is that the correct value must appear in the
> documentation somewhere.

That's not entirely the case. One can always document it as (I
sloppily do below):

"All cairo surface types have a get_type() function. You can compare
the result of this function against any cairo_foo_surface_t_get_type()
function, for appropriate values of foo_surface_t."

> And I'm arguing that since this function returns a value, and that
> value is documented in this same manual, then the documentation for
> this function must provide a link to the relevant location in the
> manual. Anything less is too unkind to the reader.

True, but there's a happy medium between enumerating all possible
types and saying "here are functions where you can figure out what to
compare its return value against." The latter gives you a lot more
wiggle-room as an implementor.

> > Not listing all available types is a feature, not a bug.
>
> Leaving necessary information out of the documentation is never a
> feature. The only acceptable excuse for not listing (or at least
> linking to) the possible values here would be if the set of possible
> values is not known when the documentation is assembled. But that's
> not the case with cairo as it exists today.

There's probably value in being somewhat opaque here. As I understand
it, Behdad isn't arguing for no documentation in his proposed
implementation, but rather a "You don't have to document every
possible backend's type here if you document what a backend's type id
function looks like".

Best,
Dom
--
Counting bodies like sheep to the rhythm of the war drums.