[cairo] surfaces and backends

[Behdad Esfahbod]

On Fri, 24 Feb 2006, Carl Worth wrote:

> On Fri, 24 Feb 2006 17:02:10 -0500 (EST), Behdad Esfahbod wrote:
> >
> > You don't need to list them in documentation either.  Something
> > like this:
> >
> > /* cairo_surface_get_type:
> >  * Returns a unique type identifier for the surface.  You can
> >  * check whether the surface is of a certain kind, by checking
> >  * this id against the respective identifier acquired by
> >  * backend-specific type identifiers, e.g. cairo_image_surface_type.
> >  */
>
> 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.


The values are documented separately in their backend section in
the documentation.

It's really not much different than other things.  Say, lets read
the documentation for cairo_surface_t:

"""A cairo_surface_t represents an image, either as the
destination of a drawing operation or as source when drawing onto
another surface. There are different subtypes of cairo_surface_t
for different drawing backends; for example,
cairo_image_surface_create() creates a bitmap image in memory."""

So, why's not it linking to all _surface_create functions?
That's just how OO is supposed to be... well.


behdad


> 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.
>
> > 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.
>
> -Carl
>

--behdad
http://behdad.org/

"Commandment Three says Do Not Kill, Amendment Two says Blood Will Spill"
	-- Dan Bern, "New American Language"