Re: need people to add documentation to glib?

[Owen Taylor <otaylor redhat com>]

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.

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.

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.

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 ]

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.

Regards,
                                   Owen