GNOME API Documentation Format issues

[Scott Wimer <scottw dev cgibuilder com>]

Hi again folks.

I spent some time thinking about the GNOME API documentation format 
this weekend.  Basically, I tried to come up with a format that -I-
would enjoy using (or at the very least find useful).  Here's
basically what I've come up with, the context I am using is HTML,
since DocBook doesn't seem to provide all of this.

Here's the Documentation path:
 [Program | Library]
 +--> [Design Documents]
 +--> [Module Index]
   +--> [Documents for Module 'm']
     +--> [Internal links to functions in Module 'm']

A person seeking documentation for a program or a library should be
able to quickly navigate this heiarchy to get the info they are
looking for.

Here's what I see as the basic structure of the generated documents
for each Module file:

Module Header
 File Name
 Author Name and contact info
 Last modification date
 Module Description

Table of Contents
 Functions (grouped by relation, or ordered alphabetically)
  Brief 1 line description of the function
  Link to documentation for this function


Function 1
 Function Name
 Function Description
 Return Values description
 Parameter List
  Parameter Type
  Parameter Description
 -Link to Table of Contents-

Function 2
 . . .
Function N

----- 

This model of documentation has one difficulty though.  That is, some sort
of dB needs to track all the Functions for a particular program or library.
This is to make searching for documentation on a particular function name
easier.  This shouldn't be too difficult, but it would need to exist.

So, am I off the mark here?  Am I missing something?  Does this look like
it's what other people would like to see?

Regards,
scottwimer

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