Re: Documentation for GNOME API

[Martin Baulig <martin home-of-linux org>]

And that's what DocBook currently provides (randomly copied out of
gnome-libs/devel-doc/libgnorba.sgml):

<sect2 id="goad-server-activate">
<title>goad_server_activate - get a specified server</title>
<funcsynopsis><funcdef>CORBA_Object
<function>goad_server_activate</function>
</funcdef>
<paramdef>GoadServer *<parameter>sinfo</parameter></paramdef>
<paramdef>GoadActivationFlags <parameter>flags</parameter></paramdef>
</funcsynopsis>

Martin

On Tue, 20 Oct 1998, Scott Wimer wrote:

> To: Mark Galassi <rosalia@cygnus.com>,
>     Federico Mena Quintero <federico@nuclecu.unam.mx>,
>     Miguel de Icaza <miguel@nuclecu.unam.mx>
> Subject: Documentation for GNOME API
> From: 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/
> 
> 
> -- 
>          To unsubscribe: mail gnome-list-request@gnome.org with 
>                        "unsubscribe" as the Subject.
> 

-----------------------------------------------------------------
   Martin Baulig - Angewandte Mathematik - Universitaet Trier
   martin@home-of-linux.org, http://www.home-of-linux.org/
------------------------------------------------------------------