Re: need people to add documentation to glib?

[Sven Neumann <sven gimp org>]

Hi,

Guido Draheim <guidod-2003- gmx de> writes:

> I've been asking, and no replies ever. May be the situation has
> changed but I don't expect anything to happen in the documentation
> part of glib/gtk.

you are obviously not following the development. The documentation is
continously being improved.

> If you think that glib is documented to a 100% then you have
> never tried to write programs based on the interface documentation,
> the glib docs are way incomplete. in most parts the glib docs say
> what the functions "should" do but not what they "really" do. And
> there's a huge difference between these two. See this:
> 
> void
> g_ptr_array_add   g_ptr_array_add (GPtrArray *array, gpointer data)
> 
> glib official docs say:
> 
>    Adds a pointer to the end of the pointer array. The array will grow
>    in size automatically if necessary.
> 
> I've done a code review and derived this:
> 
>   This function appends the given item to the end of the internal
>   array. It will automatically increase the handle-len by one
>   and it does run a internal realloc on the ptr-array if that
>   is necessary.
> 
>   Again, this function does not return anything, an implicit
>   realloc will make for SIGSEGV before returning anyway, and so
>   this function will always succeed or continue in a crash handler
>   elsewhere (design flaw).

In my opinion this is way too verbose since it explains some
fundamental details of the GLib memory management. A developer will
not want to read this with each and every function, instead she should
have made herself familiar with the details of GLib memory handling by
reading the docs about it. Apart from that, your explanation exposes
details of the function that a casual developer should not need to
care about. The whole idea of any API is to hide the ugly details. Why
do you want to try to explain them in the docs?  Of course any
side-effects should be documented, but internal details should remain
internal.

I am not saying that the docs are perfect, I'm only saying that you
should use Bugzilla instead of ranting on public mailing lists. The
only way to ever get anything changed in glib/gtk+ is to submit
bug-reports for it and attach patches. This has been a well-known
policy for quite some time now.

> No distro does ship a set of man pages for glib, and in fact I did
> try to use the documentation to create a set of man pages but it did
> simply fail. May be you have changed it in between but when I came
> around to offer help with generating troff man pages, no answer was
> given and there was no other sign of interest in this.

Most people actually prefer the browsable HTML documentation over
man-pages. However, since man-pages seem like a good idea, I'd suggest
you help the gtk-doc developers to add the necessary make targets so
that everyone can build man-pages from the DocBook XML sources.
Perhaps add a PDF target as well, while you are at it...


Salut, Sven