Re: GDataInputStream API return types

[Emmanuele Bassi <ebassi gmail com>]

hi;

On 28 November 2012 13:56, 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".
>
> 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.

the original idea was to have gtk-doc generate the doc strings through
the annotations; this would have required changing every single user
of gtk-doc to avoid comments like: "Return value: (transfer full): the
line read from the stream; free the resources allocated when done"
rendered as "Return value: the line read from the stream; free the
resources allocated when done. Free the resources allocated when
done.". also, the annotations lack way to express the function to
actually free the resources.

ciao,
 Emmanuele.

--
W: http://www.emmanuelebassi.name
B: http://blogs.gnome.org/ebassi/