[cairo] surfaces and backends

[Behdad Esfahbod]

On Fri, 24 Feb 2006, Carl Worth wrote:

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

I was just trying to say that it's no different.  Of course,
having a page listing all backends is pretty useful.

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

Well, it is implementing the OO concept anyway :).  What I was
refering to specifically was that a parent type
(does|should)n't (need)? to know about it's subtypes.


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

I agree that an enum is easier, nicer, and faster to use in a
switch.  Anyway, your call.  Doesn't make any huge difference *at
this point*.

> -Carl

--behdad
http://behdad.org/

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