Re: GDataInputStream API return types

[David King <amigadave amigadave com>]

On 2012-11-28 12:38, Henrique Camargo <henrique henriquecamargo com> wrote:
> 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.

OK. I admit that it took me a little while to realise about the title 
text too.

> 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

It is possible to view the GTK+ documentation with the same CSS (which 
is the default gtk-doc style, I think) by installing the relevant 
documentation package locally and then either using Devhelp (a really 
useful tool, by the way) or opening the files with a browser. They 
should be located at:

/usr/share/gtk-doc/html/gtk3

where gtk3 can be replaced with any other package for which you have 
documentation.

To improve the developer.gnome.org CSS, I would suggest filing a bug:

https://bugzilla.gnome.org/enter_bug.cgi?product=website

against the developer.gnome.org component. It should be quite easy to 
fix. The CSS files can be found in the library-web module:

http://git.gnome.org/browse/library-web/tree/data/skin

Please post back on the list when you file the bug, and I (or one of the 
library-web maintainers) can look into it.

--
http://amigadave.com/