Re: need people to add documentation to glib?

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

Sven Neumann wrote:
> Hi,
>
>
> > 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 a developer, I am working with glib a lot, and I want
all the details that MATTER. Among those are details that we
call "post conditions". My documentation does describe the
post conditions to a degree that one can get a clue when
something does just go wrong during writing new code. May be
the wording feels a bit verbose to you, the information in
the text however should be there.

Secondly, assume I am developer, and I picked a funcationcall
that I need to handle that datatype, now I want to do
`man functionname` and get the information necessary to actually
implant that code correctly into the application that I am just
writing. May be you have taken those dozen years to have memorized
all functions of glib and all details of all overviews in
the documentation, a usual developer does just want to use
those parts he needs, and he wants proper documentation that
does explain things to a degree to create good programs.

May be it has slipped under your eyes, but glib is not a small
library anymore but at the same time provides a lot of
functionality that one should just pick up when there is a need
for it. To give you a clue of the situation: image you are
writing up some c++ code and you've been noted that there is
some STL datatype around to handle vectors. Do you feel that
one must read the entire STL documentation to write good code?

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

I am a developer, and I do not want to search google for a functioncall
and its descriptions, possibly skipping over a number of old entries.
From my experiences, most developers (contrary to your view) prefer
to type `man functionname` over click-and-browe into html documentation.
I have offered help and with the freespace.sf.net/glib-man project I
can assure you to be able to do it. The offer is still there but I still
doubt there is real interest in this. You need to tweak the doc parser
to assemble a family of related functions and symbols on a page and
provide them with valid hints. So far, gtk doc people seem to be too
autistic to listen to advise from someone as crazy enough to actually
prefer `man functionname` over their webserver listings.

Let me add that I do want to honour the work of glib doc writers of
what they have done in the meantime but I doubt they do actually
honour the work of people who have a different vision on things,
and it is questionable to invest work that will be stomped with
saying "we don't need that, we have that in mind, and everyone else
can have that in mind when reading that other section" with the
slight meaning that every other developer is stupid and it is just
mere luck to have written some good programs otherwise. May be I do
care when not many others do.

is that harsh enough?
-- greetings, guido
p.s. I take patches...