[cairo] surfaces and backends

[Carl Worth]

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.

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060224/3110e98b/attachment.pgp