GNOME.org
 

Re: need people to add documentation to glib?


Owen Taylor schrieb:

On Wed, 2003-04-09 at 13:10, Guido Draheim wrote:


Silence again?

Anyway, how to bring up a decision that

(a) glib methods should be fully documented with their set of
    pre-conditions and post-conditions. A lot of functions
    have some check-functions in their implementation to
    print a warning and return with a value which can help
    in deriving pre-conditions and that should be in the
    docs so that developers don't need to read the source
    code of glib.
I don't think formal pre-condition and post-condition descriptions in the docs would help. In general, mentioning restrictions that aren't implied by the rest of the docs is something that should be done, but if the docs for g_hash_table_insert(): 

 * g_hash_table_insert:
 * @hash_table: a #GHashTable.
 * @key: a key to insert.
 * @value: the value to associate with the key.
[...] Were extended to say: precondition: hash_table != NULL 

that would just be ridiculous and would detract seriously
from the utility of the docs.


In some cases like these it is better to go the other
way round - e.g. for glist you may provide a null object
on additions which should be noted explicitly while a
ghash should be initialized of course.

To stick with the example (which doesn't suit me too well ;-))
one might want to note whether value/key may be null or
not - well, here it is actually dependent on your destroyer
callbacks. There are other examples where such conditions
should be documented and give more hints than it would here.



My goal for the documentation I write, especially for GLib,
where the functions typically have more easily described
behavior, is that the function documentation should be
sufficient to allow someone to reimplement the function
without looking at the sources. Is all the GLib documentation
up to that standard? Not by any means, but I think it's
a useful benchmark.


agreed. Perhaps that's a better description than speaking
of "pre- and post-conditions" in general since some things
are implied as "must be that way" in the mind of an average
programmer. Well, however, we do have a cognitive problem
here as well, see how many system makers have interpreted
even posix standard functions differently than me would
think them they should be ;-) so perhaps a bit more is
better then, isn't it.



We have a full-documentation policy for all new additions
to GLib and GTK+. Contributions of documentation for the
missing pieces are welcomed. (The missing documentation is mostly for GObject though, and is mostly missing because the stuff that isn't documented is obscure and hard to understand.) 



(b) create extensions on the documentation processor to
    get at a docbook master xml file that can be turned
    into proper troff man pages. It would need to include
    per-function manpages and it would be good to have them
    contain cross-references to overview pages that decribe
    in short words a function family and their design.



Feel free to work to improve the docbook2man system
or work on alternate docbook2man that produces better
manual page.


I'm using xmlto successfuly for a long time, it's shipped
as a standard package in redhat systems and I've built
rpm packages for other systems as well. It uses the
libxslt's xsltproc and the xml stylesheets from docbook
org. Works great and there are less installation problems
on other systems, I did never made docbook2man work on
solaris systems, ye know, and it did not rebuild nicely
on most linux systems that I came across.
But producing good docbook is the goal for the project, not producing quasi-docbook output that is converted somehow converted to man pages. 
[ My opinion is that man pages don't work very well for
  OO systems. A GtkWidget man page is too big to be useful,
  a gtk_widget_show() man page is too small to be useful ]


That's about right - I am usually grouping the OO methods
that have a similar thing and then describing the things
to help the programmer to pick the better thing - e.g.
there are quite usually a number of _new functions or
_add functions available. That's best so that you just
think in your mind "okay, I need a new xx widget, what
methods are there to get one".

btw, bash completion is great, man gtk_widget_<tab><tab>
is really nice to get an overview, and it is right
there at hand. :-)=)
And yes, this is really completely the wrong list. gtk-doc-list is the right place for discussing the documentation tools used in GTK+, gtk-devel-list the right place for discussing development policies. 



Hmmm, and I wondered why the gtk-doc list shows so
little traffic, one might get the impression there is
nothing going on about gtk doc tools. So it seems,
those discussion have been going on in gtk-devel then.

-- cheers, guido
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]