Re: need people to add documentation to glib?

[Guido Draheim <guidod-2003- gmx de>]

Sven Neumann wrote:
> Hi,
>
> Guido Draheim <guidod-2003- gmx de> writes:
>
>
> > For other glib documentation, you might want to look at the parts
> > that I've assembled over time from my experiences and reading
> > glib source code. Nobody seems to be interested to properly
> > document glib
>
>
> you must be kidding. Of course there's interest and actually GLib (not
> GObject) is 100% documented. If you think this can be improved, you
> should use Bugzilla to submit patches to the existing documentation.

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.

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).


> > or to have troff man pages generated
>
>
> AFAIK, you can generate man-pages from the very same Docbook XML
> sources that the HTML pages are generated from. Try docbook2man.

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.

You might feel confident in what you say but the actions of
glib doc people had been way different to a degree I was not
amuzed. And no, I am not kidding as this felt very real. You
have a red pill at hand?

-- cheers, guido