Documentation for GNOME APIs

[Scott Wimer <scottw dev cgibuilder com>]

I've been working on the parser to pull the documentation for the API 
functions out from the .c files.  I've also started to go through the 
DocBook guide.  Naturally, this has resulted in some questions. :)

Here they are, in more or less the order that I realized them:

1.  Should I make a table of contents for all of the documentation
    read from a particular file?  Maybe using the <toc> stuff, or
    maybe using the <lot> (since it's non heirarchical).

2.  Should the format of the DocBook entry for each function look
    something like this:

 <FUNCSYNOPSIS>
 <FUNCSYNOPSISINFO>
  Description of the function from source file.
 </FUNCSYNOPSISINFO>
 <FUNCDEF>Return value from source file
  <FUNCTION>function name from source file</FUNCION>
 </FUNCDEF>
 <PARAMDEF>parameter type info from source file
  <PARAMETER>parameter name</PARAMETER>
 </PARAMDEF>
 </FUNCSYNOPSIS>

I'm not yet sure where the description of the returned values would go.
Offhand, I'm thinking of putting it in with rest of the description,
just following it.

If this format is more or less what I need to be shooting for, we should 
have this rolling really shortly. :)

regards,
scottwimer
--
Scott Wimer
play  --->    scottw@cgibuilder.com         http://www.cgibuilder.com/
work  --->    scottw@corp.earthlink.net     http://www.earthlink.net/