Fully documenting the GNOME api

[Miguel de Icaza <miguel nuclecu unam mx>]

Hello lovers of the documentation process of Gnome-libs,

   I have checked in on the CVS the basic framework that Damon
provided us with for documenting the API of gnome-libs (currently only
the libgnome and libgnomeui have templates created).

   We need volunteers to complete the API documentation of the
gnome-libs.  This is a very important task to make the GNOME libraries
easier to use to new programmers.

   Here is the status of the documentation system:

   1. gtk-doc module provides the documentation system (it generates
      docbook for us).  

   2. Volunteers need to edit the "template" files created by
      gtk-doc.  

      Now, you do not need to fill neither the parameter definition,
      nor return values nor the function description.  These are
      provided in the source code of gnome-libs and gtk-doc
      automatically merges the source code in-line api-doc comments
      with the template files to produce the actual Docbook source.

   3. Many things that before were documenting in .txt files and 
      were just placeholders for information should move into the
      template files.

   4. The template files allow us to provide a long description of a
      GNOME module, with all of the information we want to convey to
      the programmers.

   5. Examples.  You can provide example usage of the various API
      routines in the template file.  This is highly recomended.
   
      There is a sample file that shows you how you can annotate
      source code in the gnome-libs/devel-docs directory
      (annotate.sgml is the name of the file).

   6. Coordination.  If you start documenting something, please, post
      to the list to avoid duplicating effort.

Good night,
Miguel.