Re: GDataInputStream API return types

[Henrique Camargo <henrique henriquecamargo com>]

On Wed, Nov 28, 2012 at 11:56 AM, David King <amigadave amigadave com> wrote:
> The "transfer full" annotation is given on the return type, and the title
> text is "free data after the code is done".

I have imagined that the annotation could mean that the data should be
freed but I didn't notice the title text at the time.

> It would be good to have some guidance on whether the annotation (and the
> corresponding acronym tag in the documentation) is sufficient, or whether
> each transfer annotation should also include some explicit warning of what
> is required from the programmer. I would personally favour just using the
> annotation, but maybe there are certain cases where being explicit is a
> significant improvement.

I think that the annotation alone is not clear, the title text makes
it clear though. IMHO the stylesheet for the gtk-doc generated html
used at http://developer.gnome.org should make the presence of the
title text more obvious. The stylesheet used for the gstreamer
documentation is a little better in this aspect [1].

[1] http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/annotation-glossary.html#glsO

--
Henrique Camargo

Email: henrique henriquecamargo com
Phone: +55 41 99152915