[cairo] surfaces and backends

[Carl Worth]

On Fri, 24 Feb 2006 17:26:32 -0500 (EST), Behdad Esfahbod wrote:
>
> The values are documented separately in their backend section in
> the documentation.

Right. And I'm saying that if we went with this approach, the
documentation should point directly to all the values (wherever they
are) in the documentation.

> """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?

If our documentation were complete, (and I'd learned all the syntax
for linking up various pieces), I would fix that paragraph by making
"different drawing backends" link to a section that did explicitly
list all available backends.

> That's just how OO is supposed to be... well.

Impossibly hard to follow the documentation you mean? That would
describe most "OO" systems I've seen quite well. ;-)

For the record, I wouldn't ever describe cairo as being OO
myself. And, with cairo's documentation as a glass house I really
shouldn't throw any stones at any other documentation out there.

Anyway, the point isn't really about the state of the documentation.
I'm just not convinced that there's any real benefit to avoiding a
central list of backend names in cairo.h.

As far as providing a function that maps a magic type value to a
string, an enum or a pointer to an opaque structure would work equally
well there.

-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/9395fb67/attachment.pgp