[cairo] clip-getters [patch]

[Carl Worth]

On Fri, 29 Sep 2006 20:21:47 -0400 (EDT), Andrew Johnson wrote:
>
> Or it could be that I am possibly being just a bit pedantic.
>

No, it's a good point you're making. If you read back in the thread,
what I did was make an argument against both of the proposals for
different reasons. I don't really like either name, but I also haven't
come up with anything better yet.

And since I didn't have anything better I really was leaving it up to
the person doing the work. I wouldn't have said anything at all about
the name had it gone either way, but I really didn't like seeing the
patch land with _both_ names still there.

Another twist to throw in here would be that a variant function should
really use an adjective to distinguish itself, (as we did with
_flat). But I can't think of a good adjective either, (rectilinear?
ick).

Oh, and Robert, I forgot to mention this before, but new API also
needs to have a Since: tag in the documentation to indicate the first
release that contains it. Particularly since I went and just pushed
out our documentation to the web site (oops).

Does anyone know if gtk-doc allows me to generate documentation only
for symbols that exist before a particular version? That might be a
nice way to avoid leaking our "experimental" API out into the
documentation, (without maintaining separate on-line manuals for
different versions, which is something I've wanted to avoid).

Or, and Behdad has talked about creating a "cairo_experimental"
attribute that we could use to mark API that is still under
discussion. This would be an empty define to the compiler but we would
have a check at release time to ensure we were happy with anything
marked as experimental. If we did something like that, maybe we could
also convince gtk-doc to insert a standard disclaimer about the
experimental status of some API functions into the documentation.

-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/20060929/2cd798b1/attachment.pgp