Re: Documentation for GNOME APIs

[Scott Wimer <scottw dev cgibuilder com>]

On Sat, 17 Oct 1998, Mark Galassi wrote:

>     Scott> 2.  Should the format of the DocBook entry for each
>     Scott>     function look something like this:
> 
> You pretty much have it, except that I do not use <funcsynopsisinfo>
> (though I should re-examine that: I have learned a lot since I
> developed my habits).
> 
> I append an example of how I document APIs in the eCos reference
> manual, and I would suggest that for now you output that kind of
> stuff.

I'm looking at this and the documentation for DocBook.  It looks like
you're going through some extra work to do something that I feel the
DocBook format should handle.  I'm refering to all the <varlistentry>
stuff that you're using to describe the individual paramagers.  From the 
reference documentation it appears that a better way of doing this
exists.  darn.  Here's what I'm thinking:

 It would be really nice to have a <PARAMINFO></PARAMINFO> tag.
 we could stick the description of the parameter inside of that 
 bucket, and then have DocBook format it nicely for us.  If there
 are any DocBook wizzes reading this, can this hack be added?
 The documentation covers customization, but I don't have time or
 energy to dive into that right now.

Without a <paraminfo> type tag, I'll be implementing this the way
you've got it (until somebody points me at an output format that is
more appealing to people).  In any event, new output formats are just
going to be different perl modules that get loaded, so you -should-
be able to get the documentation in any format that you want, so long
as the perl module for that format exists.

Regards,
scottwimer

> 
> This winter I will be exploring using one reference entry for each
> function in the API: I think that is the way the DocBook creators
> meant it to be, but stylesheets have only recently gotten good enough
> to do stuff with that.  I believe that if you can render what I'm
> showing you here, you will have no problem changing the scripts to use 
> reference entries.
> 
> [Here's another cute idea I just had: while you're in scripting mode,
> try to generate <cmdsynopsis> stuff from the output of any command's
> "--help" option.  That could be inserted into the hand-written manuals
> for each application, so that the command synopsis would be
> auto-maintained.]
> 
> ------------
> 
> You can see how it renders at this URL:
> http://sourceware.cygnus.com/ecos/docs/tx39/ref/ecos-ref/thread-operations.html
> 
> 	<funcsynopsis>
> 	  <funcdef>void <function>cyg_thread_create</function></funcdef>
> 	  <paramdef>cyg_addrword_t
> 	    <parameter>sched_info</parameter></paramdef>
> 	  <paramdef>cyg_thread_entry_t
> 	    *<parameter>entry</parameter></paramdef>
> 	  <paramdef>cyg_addrword_t<parameter>entry_data</parameter></paramdef>
> 	  <paramdef>char *<parameter>name</parameter></paramdef>
> 	  <paramdef>void *<parameter>stack_base</parameter></paramdef>
> 	  <paramdef>cyg_ucount32
> 	    <parameter>stack_size</parameter></paramdef>
> 	  <paramdef>cyg_handle_t *<parameter>handle</parameter></paramdef>
> 	  <paramdef>cyg_thread *<parameter>thread</parameter></paramdef>
> 	</funcsynopsis>
> 
>       <para>
> 	  Creates a thread in a suspended state.  The thread will not
> 	  run until it has been resumed with
> 	  <function>cyg_thread_resume()</function> and the scheduler
> 	  has been started with
> 	  <function>cyg_scheduler_start()</function>.</para>
> 
>       <para>Here is a description of the parameters of
>       <function>cyg_thread_create()</function>:</para>
> 
>       <variablelist>
> 	<varlistentry>
> 	  <term><parameter>sched_info</parameter></term>
> 	  <listitem><para>
> 		Information to be passed to the scheduler.  For almost
> 		all schedulers this is a simple priority value, and
> 		you can simply pass a nonnegative integer when you
> 		create the thread.
> 	      </para></listitem>
> 	</varlistentry>
> 	<varlistentry>
> 	  <term><parameter>entry</parameter></term>
> 	  <listitem>
> 	    <para>A user-supplied function: it is routine that
> 	      begins execution of the new thread.  This function takes
> 	      a single argument of type <type>cyg_addrword_t</type>,
> 	      which is usually a pointer to a block of data, which
> 	      allows <function>cyg_scheduler_start()</function> to
> 	      pass data to this particular thread.</para>
> 	    <para>Here is a typedef for the
> 	      <parameter>entry</parameter> function:
> 	    </para>
> 	    <programlisting>
> typedef void cyg_thread_entry_t(cyg_addrword_t);</programlisting>
> 	  </listitem>
> 	</varlistentry>
> 	<varlistentry>
> 	  <term><parameter>entry_data</parameter></term>
> 	  <listitem><para>A data value passed to the
> 		<parameter>entry</parameter> function. This may be
> 		either a machine word datum or the address of a block
> 		of data.</para>
> 	  </listitem>
> 	</varlistentry>
> 	<varlistentry>
> 	  <term><parameter>name</parameter></term>
> 	  <listitem><para>A C string with the name of this
> 	  thread.</para></listitem>
> 	</varlistentry>
> 	<varlistentry>
> 	  <term><parameter>stack_base</parameter></term>
> 	  <listitem><para>The address of the stack base.  If this
> 		value is <parameter>NULL</parameter> then
> 		<function>cyg_thread_create()</function> will choose a
> 		stack base.</para>
> 	      <note><para>Passing a stack base of
> 		<parameter>NULL</parameter> is not supported in this
> 		release.  You must pass a real address for the stack
> 		base.</para>
> 	      </note>
> 	  </listitem>
> 	</varlistentry>
> 	<varlistentry>
> 	  <term><parameter>stack_size</parameter></term>
> 	  <listitem>
> 	      <para>The size of the stack for this thread.  If this is
> 		0, the default stack size will be used for this thread.</para>
> 	      <note><para>Passing a stack size of 0 is not supported
> 		  in this release.  You must pass a real stack
> 		  size.</para>
> 	      </note>
> 	  </listitem>
> 	</varlistentry>
> 	<varlistentry>
> 	  <term><parameter>handle</parameter></term>
> 	  <listitem><para><function>cyg_thread_create()</function>
> 	      returns the thread handle in this location.</para>
> 	  </listitem>
> 	</varlistentry>
> 	<varlistentry>
> 	  <term><parameter>thread</parameter></term>
> 	  <listitem><para>The thread housekeeping information is
> 		placed in the memory pointed to by this parameter. If
> 		this pointer is <parameter>NULL</parameter> then the
> 		memory will be allocated.
> 	      <note>
> 		<para>Passing a NULL value for the thread data
> 		    structure address is not supported in this
> 		    release. You must pass a valid address.
> 		</para>
> 	      </note>
> 	    </para>
> 	  </listitem>
> 	</varlistentry>
>       </variablelist>
> 
> 
> 

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