Re: Documentation for GNOME APIs

[Mark Galassi <rosalia cygnus com>]

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

I would not use the <toc> tags, or I'd leave them empty.  The DSSSL
stylesheets create TOCs.

    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.

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>