API Documentation standard

[Derek Simkowiak <dereks kd-dev com>]

	I am preparing some source code for submittal to Glib.  It'll be a
while before I actually submit it (because I want to write my sample
application first, to prove its usefulness :) but I want to get into the
right documenting habits.

	Currently I have a "Description:", "Inputs:", "Outputs:",
"Preconditions:", and "Postconditions:" comments in front of every
function in my .h file.  However, my formatting sucks, because I don't use 
or understand Emacs or vi.  Here is a sample:


/* g_skip_list_nth()
Description: Gets the GSkipNode at position n, where n starts at zero.
	This operation is very fast.
Inputs: head: The 'head' of your SkipList
	n: the position of the element you want to retrieve, starting at zero
Outputs: The GSkipNode at position n (counting from zero), or NULL if
	position is off the end of the list.
Preconditions: 'head' should point to a valid, initialized SkipList.
Postconditions: none.
*/
GSkipNode *g_skip_list_nth(GSkipNode *head, guint n);


	How is reference documentation generated for the existing
Glib/Gtk+?  What tools are used?  I thought there was a white paper about
this, if so, please point me to it.

	I ask because I'm hoping there is there an equivalent of Kdoc for
Gtk+/Gnome.  Kdoc uses specially-formatted comments in front of Qt's C++
classes to generate nicely-formatted HTML or Postscript documentation from
the header files. I have not seen any specially-formatted comments in the
Gtk+ source, so I assume there is no such tool.  Kdoc turns the following
styled comment into a cross-referenced, pretty HTML file:

  /**
        * Short description of this class
        *
        * This is a longer description of my class.  It does the following
        * @li Some bulleted thing
        * @li Some other bulleted thing
        *  You should use it when ...  It's not appropriate for ...
        *
        * @author My Name <myemail@wherever.edu>
        * @version 0.0.1
        **/

     class KMyClass
     {
             .
       /**
        * Describe method.  It takes <i>argument</i> to mean ...
        *
        * @return A pointer to another class
        * @see KOtherClass
        **/
        KOtherClass *method (int argument);
     }


	It would be very cool if I could properly-format the comments in
my header and have the documentation automatically generated.

	Please advise.  I strongly believe that header files should
document the code, but I don't want to maintain both .h files *and* SGML
files separately.  (One of them is sure to become out of date, etc.)  If
there is no Kdoc equivalent, I may even be willing to write such a tool...


Thank You,
Derek Simkowiak
dereks@kd-dev.com