Documentation for GNOME API

[Scott Wimer <scottw dev cgibuilder com>]

I've been looking at documentation on DocBook, and I'm thinking that
it's going to need some help before it's useful for the API
documentation.  Basically, What I see as the primary problem with
DocBook is that it doesn't provide any way (that I can find) to
associate the description of a function and it's parameters with 
the function prototype.

The <funcsynopsisinfo> tag looks like it may give us a place to
put the function description.  But, we're still left without any
way to decently handle the parameter descriptions or the 
description of the return(ed) value(s).

It should be possible to create a derivetive of the DocBook DTD that
contains tags for handling this.  I'm not a DocBook expert though.
I suppose that I could get good enough to make these changes, but
it would probably be faster if somebody already knowledgeble were to
do it. :)

here's my initial thoughts for what -I- think we want:

<FUNCSYNOPIS id="function_name">
 <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>
  <PARAMINFO>parameter description</PARAMINFO>
 </PARAMDEF>
 <FUNCRETURNINFO>Description of the values returned from the function
 </FUNCRETURNINFO>
</FUNCSYNOPSIS>

We could then link to functions by name fairly easily.  Potentially, we
might also want to include an 'id' for each of the parameters.

Well, its about time for me to go to bed.  Please let me know what
you think about this type of documentation setup.  To see the current
DocBook stuff that's being produced automatically, go to:
http://dev.cgibuilder.com/scottw/scripts/docbook/doc-book-version.output

The perl script that strips the docu-comments out is linked to from:
http://dev.cgibuilder.com/scottw/scripts/docbook/api-read-dox.txt

The perl module that actually generates the DocBook code is:
http://dev.cgibuilder.com/scottw/scripts/docbook/StoreDocBook.pm

Regards,
scottwimer


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