improve reference documentation

git-svn-id: svn://svn.linux1394.org/libraw1394/trunk@150 53a565d1-3bb7-0310-b661-cf11e63c67ab

2 files changed, 616 insertions, 233 deletions

diff --git a/doc/libraw1394.sgml b/doc/libraw1394.sgml
index 17ec18f..8b4e394 100644
--- a/doc/libraw1394.sgml
+++ b/doc/libraw1394.sgml
@@ -971,6 +971,12 @@
    Allocates all user and kernel resources necessary for isochronous transmission.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1044,7 +1050,7 @@
    <term><parameter>mode</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      bufferfill or packet per buffer mode
     </para>
    </listitem>
   </varlistentry>
@@ -1065,6 +1071,12 @@
    Allocates all user and kernel resources necessary for isochronous reception.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1140,6 +1152,12 @@
    Allocates all user and kernel resources necessary for isochronous reception.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1175,7 +1193,7 @@
    <term><parameter>channel</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the channel to start listening
     </para>
    </listitem>
   </varlistentry>
@@ -1184,7 +1202,13 @@
 <refsect1>
  <title>Description</title>
  <para>
-   listen/unlisten on a specific channel (multi-channel mode ONLY)	
+   listen/unlisten on a specific channel (multi-channel mode ONLY)
+ </para>
+</refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
  </para>
 </refsect1>
 </refentry>
@@ -1222,12 +1246,18 @@
    <term><parameter>channel</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the channel to stop listening to
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1276,6 +1306,12 @@
    for multi-channel reception mode only
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success, -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1328,6 +1364,12 @@
   </varlistentry>
  </variablelist>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1388,6 +1430,12 @@
   </varlistentry>
  </variablelist>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1465,6 +1513,12 @@
    errno = EAGAIN
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1497,6 +1551,12 @@
   </varlistentry>
  </variablelist>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1542,6 +1602,12 @@
    will be flushed out to user space.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1641,17 +1707,20 @@
 <refsect1>
  <title>Description</title>
  <para>
-   Returns the error code of the last <function>raw1394_read</function>, <function>raw1394_write</function>,
-   <function>raw1394_lock</function> or <function>raw1394_iso_write</function>.  The error code is either an internal
-   error (i.e. not a bus error) or a combination of acknowledge code and
-   response code, as appropriate.
-   </para><para>
-
    Some macros are available to extract information from the error code,
    <function>raw1394_errcode_to_errno</function> can be used to convert it to an errno number of
    roughly the same meaning.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    the error code of the last <function>raw1394_read</function>, <function>raw1394_write</function>,
+   <function>raw1394_lock</function> or <function>raw1394_iso_write</function>.  The error code is either an internal
+   error (i.e. not a bus error) or a combination of acknowledge code and
+   response code, as appropriate.
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1697,9 +1766,12 @@
    the conversion.  However the returned errnos are equivalent in source code
    meaning only, the associated text of e.g. <function>perror</function> is not necessarily
    meaningful.
-   </para><para>
-
-   Returned values are <constant>EAGAIN</constant> (retrying might succeed, also generation number
+ </para>
+</refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    <constant>EAGAIN</constant> (retrying might succeed, also generation number
    mismatch), <constant>EREMOTEIO</constant> (other node had internal problems), <constant>EPERM</constant> (operation
    not allowed on this address, e.g. write on read-only location), <constant>EINVAL</constant>
    (invalid argument) and <constant>EFAULT</constant> (invalid pointer).
@@ -1746,9 +1818,12 @@
    port.  It is not allowed to use the same handle in multiple threads or forked
    processes.  It is allowed to create and use multiple handles, however.  Use
    one handle per thread which needs it in the multithreaded case.
-   </para><para>
-
-   Returns the created handle or <constant>NULL</constant> when initialization fails.  In the latter
+ </para>
+</refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    the created handle or <constant>NULL</constant> when initialization fails. In the latter
    case errno either contains some OS specific error code or <constant>0</constant> if the error is
    that libraw1394 and raw1394 don't support each other's protocol versions.
  </para>
@@ -1835,6 +1910,12 @@
    <function>raw1394_set_port</function> returns ESTALE, retries automatically.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    the new handle on success or NULL on failure
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -1870,18 +1951,16 @@
    <term><parameter>off_on_switch</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      RAW1394_NOTIFY_OFF or RAW1394_NOTIFY_ON
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1>
- <title>returns</title>
+ <title>Returns</title>
  <para>
-   ==0 success 
-   !=0 failure
-   off_on_switch .... RAW1394_NOTIFY_OFF or RAW1394_NOTIFY_ON
+    0 on success or -1 on failure (sets errno)
  </para>
 </refsect1>
 </refentry>
@@ -1919,14 +1998,19 @@
 <refsect1>
  <title>Description</title>
  <para>
-   Returns the fd used for communication with the raw1394 kernel module.  This
-   can be used for <function>select</function>/<function>poll</function> calls if you wait on other fds or can be
+   This can be used for <function>select</function>/<function>poll</function> calls if you wait on other fds or can be
    integrated into another event loop (e.g. from a GUI application framework).
    It can also be used to set/remove the O_NONBLOCK flag using <function>fcntl</function> to modify
    the blocking behaviour in <function>raw1394_loop_iterate</function>.  It must not be used for
    anything else.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    the fd used for communication with the raw1394 kernel module.
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -2010,9 +2094,9 @@
  </variablelist>
 </refsect1>
 <refsect1>
- <title>Description</title>
+ <title>Returns</title>
  <para>
-   Returns the user data pointer associated with the handle using
+    the user data pointer associated with the handle using
    <function>raw1394_set_userdata</function>.
  </para>
 </refsect1>
@@ -2049,9 +2133,9 @@
  </variablelist>
 </refsect1>
 <refsect1>
- <title>Description</title>
+ <title>Returns</title>
  <para>
-   Returns the node ID of the local node connected to which the handle is
+    the node ID of the local node connected to which the handle is
    connected.  This value can change with every bus reset.
  </para>
 </refsect1>
@@ -2088,9 +2172,9 @@
  </variablelist>
 </refsect1>
 <refsect1>
- <title>Description</title>
+ <title>Returns</title>
  <para>
-   Returns the node ID of the isochronous resource manager of the bus the handle
+    the node ID of the isochronous resource manager of the bus the handle
    is connected to.  This value may change with every bus reset.
  </para>
 </refsect1>
@@ -2129,12 +2213,18 @@
 <refsect1>
  <title>Description</title>
  <para>
-   Returns the number of nodes on the bus to which the handle is connected.
-   This value can change with every bus reset.  Since the root node always has
+   Since the root node always has
    the highest node ID, this number can be used to determine that ID (it's
    LOCAL_BUS|(count-1)).
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    the number of nodes on the bus to which the handle is connected.
+   This value can change with every bus reset.
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -2195,14 +2285,17 @@
    If your program is interactive, you should present the user with this list to
    let them decide which port to use if there is more than one.  A
    non-interactive program (and probably interactive ones, too) should provide a
-   command line option to choose the port.
-   </para><para>
-
-   Returns the number of ports and writes information about them into <parameter>pinf</parameter>, but
-   not into more than <parameter>maxports</parameter> elements.  If <parameter>maxports</parameter> is <constant>0</constant>, <parameter>pinf</parameter> can be
+   command line option to choose the port. If <parameter>maxports</parameter> is <constant>0</constant>, <parameter>pinf</parameter> can be
    <constant>NULL</constant>, too.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    the number of ports and writes information about them into <parameter>pinf</parameter>, but
+   not into more than <parameter>maxports</parameter> elements.
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -2252,9 +2345,12 @@
    <function>raw1394_set_port</function> are not allowed to be called afterwards on this handle.
    To make up for this, all the other functions (those handling asynchronous and
    isochronous transmissions) can now be called.
-   </para><para>
-
-   Returns <constant>0</constant> for success and -1 for failure with errno set appropriately.  A
+ </para>
+</refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    <constant>0</constant> for success or -1 for failure with errno set appropriately.  A
    possible failure mode is with errno = <constant>ESTALE</constant>, in this case the configuration
    has changed since the call to <function>raw1394_get_port_info</function> and it has to be called
    again to update your view of the available ports.
@@ -2303,7 +2399,7 @@
 <refsect1>
  <title>Returns</title>
  <para>
-    <constant>0</constant> for success and -1 for failure with errno set appropriately.
+    <constant>0</constant> for success or -1 for failure with errno set appropriately
  </para>
 </refsect1>
 </refentry>
@@ -2341,18 +2437,16 @@
    <term><parameter>type</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      RAW1394_SHORT_RESET or RAW1394_LONG_RESET
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1>
- <title>returns</title>
+ <title>Returns</title>
  <para>
-   -1 failure 
-   0  success
-   type .... RAW1394_SHORT_RESET or RAW1394_LONG_RESET
+    <constant>0</constant> for success or -1 for failure 
  </para>
 </refsect1>
 </refentry>
@@ -2391,13 +2485,16 @@
  <title>Description</title>
  <para>
    Get one new message through handle and process it with the registered message
-   handler.  This function will return <constant>-1</constant> for an error or the return value of
-   the handler which got executed.  The default handlers always return zero.
-   </para><para>
-
-   Note that some other library functions may call this function multiple times
-   to wait for their completion, some handler return values may get lost if you
-   use these.
+   handler. Note that some other library functions may call this function 
+   multiple times to wait for their completion, some handler return values may 
+   get lost if you use these.
+ </para>
+</refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    <constant>-1</constant> for an error or the return value of
+   the handler which got executed. The default handlers always return zero.
  </para>
 </refsect1>
 </refentry>
@@ -2444,8 +2541,14 @@
 <refsect1>
  <title>Description</title>
  <para>
-   Sets the handler to be called on every bus reset to <parameter>new_h</parameter> and returns the
-   old handler. The default handler just calls <function>raw1394_update_generation</function>.
+   Sets the handler to be called on every bus reset to <parameter>new_h</parameter>.
+   The default handler just calls <function>raw1394_update_generation</function>.
+ </para>
+</refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    the old handler
  </para>
 </refsect1>
 </refentry>
@@ -2483,16 +2586,19 @@
 <refsect1>
  <title>Description</title>
  <para>
-   This function returns the generation number associated with the handle.  The
-   generation number is incremented on every bus reset, and every transaction
+   The generation number is incremented on every bus reset, and every transaction
    started by raw1394 is tagged with the stored generation number.  If these
    don't match, the transaction will abort with an error.
-   </para><para>
-
    The generation number of the handle is not automatically updated,
    <function>raw1394_update_generation</function> has to be used for this.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    the generation number associated with the handle 
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -2591,8 +2697,8 @@
 <refsect1>
  <title>Description</title>
  <para>
-   Sets the handler to be called whenever a request completes to <parameter>new_h</parameter> and
-   returns the old handler.  The default handler interprets the tag as a pointer
+   Sets the handler to be called whenever a request completes to <parameter>new_h</parameter>.
+   The default handler interprets the tag as a pointer
    to a &amp;struct raw1394_reqhandle and calls the callback in there.
    </para><para>
 
@@ -2602,6 +2708,12 @@
    raw1394_reqhandle as the tag and expect the callback to be invoked.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    the old handler
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -2648,7 +2760,13 @@
  <para>
    Set the handler that will be called when an async read/write/lock arm_request
    arrived. The default action is to call the arm_callback in the 
-   raw1394_arm_reqhandle pointed to by arm_tag.  Returns old handler.
+   raw1394_arm_reqhandle pointed to by arm_tag.
+ </para>
+</refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    old handler
  </para>
 </refsect1>
 </refentry>
@@ -2699,14 +2817,17 @@
    </para><para>
 
    Sets the handler to be called when either FCP command or FCP response
-   registers get written to <parameter>new_h</parameter> and returns the old handler.  The default
-   handler does nothing.
-   </para><para>
-
+   registers get written to <parameter>new_h</parameter>.  The default handler does nothing.
    In order to actually get FCP events, you have to enable it with
    <function>raw1394_start_fcp_listen</function> and can stop it with <function>raw1394_stop_fcp_listen</function>.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    the old handler
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -2733,7 +2854,7 @@
    <term><parameter>req_callback_t</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      This is the general request handler
     </para>
    </listitem>
   </varlistentry>
@@ -2742,8 +2863,6 @@
 <refsect1>
  <title>Description</title>
  <para>
-   </para><para>
-
    It is used by the default tag handler
    when a request completes, it calls the callback and passes it the data
    pointer and the error code of the request.
@@ -2775,7 +2894,7 @@
    <term><parameter>arm_req_callback_t</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      This is the general arm-request handle
     </para>
    </listitem>
   </varlistentry>
@@ -2904,10 +3023,9 @@
  </para>
 </refsect1>
 <refsect1>
- <title>returns</title>
+ <title>Returns</title>
  <para>
-               0  ... success
-   &lt;0 ... failure
+    0 on success or -1 on failure (sets errno)
  </para>
 </refsect1>
 </refentry>
@@ -2954,10 +3072,9 @@
  </variablelist>
 </refsect1>
 <refsect1>
- <title>returns</title>
+ <title>Returns</title>
  <para>
-              0  ... success
-   &lt;0 ... failure
+    0 on success or -1 on failure (sets errno)
  </para>
 </refsect1>
 </refentry>
@@ -2989,7 +3106,7 @@
    <term><parameter>handle</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      libraw1394 handle
     </para>
    </listitem>
   </varlistentry>
@@ -3028,10 +3145,9 @@
  </para>
 </refsect1>
 <refsect1>
- <title>returns</title>
+ <title>Returns</title>
  <para>
-          0  ... success
-   &lt;0 ... failure, and errno - error code
+    0 on success or -1 on failure (sets errno)
  </para>
 </refsect1>
 </refentry>
@@ -3102,10 +3218,9 @@
  </para>
 </refsect1>
 <refsect1>
- <title>returns</title>
+ <title>Returns</title>
  <para>
-          0  ... success
-   &lt;0 ... failure, and errno - error code
+    0 on success or -1 on failure (sets errno)
  </para>
 </refsect1>
 </refentry>
@@ -3158,10 +3273,9 @@
  </para>
 </refsect1>
 <refsect1>
- <title>returns</title>
+ <title>Returns</title>
  <para>
-          0 .... success
-   &lt;0 ... failure
+    0 on success or -1 on failure (sets errno)
  </para>
 </refsect1>
 </refentry>
@@ -3204,10 +3318,9 @@
  </para>
 </refsect1>
 <refsect1>
- <title>returns</title>
+ <title>Returns</title>
  <para>
-          0 .... success
-   &lt;0 ... failure
+    0 on success or -1 on failure (sets errno)
  </para>
 </refsect1>
 </refentry>
@@ -3245,7 +3358,69 @@
    <term><parameter>data</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the contents of the packet
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</refsect1>
+<refsect1>
+ <title>Description</title>
+ <para>
+   examples of physical requests are linkon, physicalconfigurationpacket, etc.
+ </para>
+</refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
+</refentry>
+
+<refentry>
+<refmeta>
+<refentrytitle><phrase id="API-raw1394-start-phy-packet-write">raw1394_start_phy_packet_write</phrase></refentrytitle>
+</refmeta>
+<refnamediv>
+ <refname>raw1394_start_phy_packet_write</refname>
+ <refpurpose>
+      initiate sending a physical request
+ </refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+ <title>Synopsis</title>
+  <funcsynopsis><funcprototype>
+   <funcdef>int <function>raw1394_start_phy_packet_write </function></funcdef>
+   <paramdef>raw1394handle_t <parameter>handle</parameter></paramdef>
+   <paramdef>quadlet_t <parameter>data</parameter></paramdef>
+   <paramdef>unsigned long <parameter>tag</parameter></paramdef>
+  </funcprototype></funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+ <title>Arguments</title>
+ <variablelist>
+  <varlistentry>
+   <term><parameter>handle</parameter></term>
+   <listitem>
+    <para>
+      libraw1394 handle
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>data</parameter></term>
+   <listitem>
+    <para>
+      the contents of the packet
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term><parameter>tag</parameter></term>
+   <listitem>
+    <para>
+      data to identify the request to completion handler
     </para>
    </listitem>
   </varlistentry>
@@ -3258,10 +3433,9 @@
  </para>
 </refsect1>
 <refsect1>
- <title>returns</title>
+ <title>Returns</title>
  <para>
-          0 .... success
-   &lt;0 ... failure
+    0 on success or -1 on failure (sets errno)
  </para>
 </refsect1>
 </refentry>
@@ -3344,8 +3518,7 @@
 <refsect1>
  <title>Description</title>
  <para>
-   This function starts the specified read request and returns <constant>0</constant> for success
-   and a negative number for an error, in which case errno will be set.  If
+   This function starts the specified read request. If
    <parameter>length</parameter> is <constant>4</constant> a quadlet read is initiated and a block read otherwise.
    </para><para>
 
@@ -3357,6 +3530,12 @@
    unsigned long).
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -3437,8 +3616,7 @@
 <refsect1>
  <title>Description</title>
  <para>
-   This function starts the specified write request and returns <constant>0</constant> for success
-   and a negative number for an error, in which case errno will be set.  If
+   This function starts the specified write request. If
    <parameter>length</parameter> is <constant>4</constant> a quadlet write is initiated and a block write otherwise.
    </para><para>
 
@@ -3450,6 +3628,12 @@
    unsigned long).
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -3548,10 +3732,7 @@
 <refsect1>
  <title>Description</title>
  <para>
-   This function starts the specified lock request and returns <constant>0</constant> for success
-   and a negative number for an error, in which case errno will be set.
-   </para><para>
-
+   This function starts the specified lock request.
    The transaction is only started, no success of the transaction is implied
    with a successful return of this function.  When the transaction completes, a
    <function>raw1394_loop_iterate</function> will call the tag handler and pass it the tag and
@@ -3560,6 +3741,12 @@
    unsigned long).
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -3658,10 +3845,7 @@
 <refsect1>
  <title>Description</title>
  <para>
-   This function starts the specified lock request and returns <constant>0</constant> for success
-   and a negative number for an error, in which case errno will be set.
-   </para><para>
-
+   This function starts the specified lock request.
    The transaction is only started, no success of the transaction is implied
    with a successful return of this function.  When the transaction completes, a
    <function>raw1394_loop_iterate</function> will call the tag handler and pass it the tag and
@@ -3670,6 +3854,12 @@
    unsigned long).
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -3711,7 +3901,7 @@
    <term><parameter>channel</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the isochronous channel number to send on
     </para>
    </listitem>
   </varlistentry>
@@ -3719,7 +3909,7 @@
    <term><parameter>tag</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      data to be put into packet's tag field
     </para>
    </listitem>
   </varlistentry>
@@ -3727,7 +3917,7 @@
    <term><parameter>sy</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      data to be put into packet's sy field
     </para>
    </listitem>
   </varlistentry>
@@ -3735,7 +3925,7 @@
    <term><parameter>speed</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      speed at which to send
     </para>
    </listitem>
   </varlistentry>
@@ -3743,7 +3933,7 @@
    <term><parameter>length</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      amount of data to send
     </para>
    </listitem>
   </varlistentry>
@@ -3751,7 +3941,7 @@
    <term><parameter>data</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      pointer to data to send
     </para>
    </listitem>
   </varlistentry>
@@ -3759,7 +3949,7 @@
    <term><parameter>rawtag</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      data to identify the request to completion handler
     </para>
    </listitem>
   </varlistentry>
@@ -3772,6 +3962,12 @@
    tag handler.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -3811,7 +4007,7 @@
    <term><parameter>length</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the amount of quadlets of data to send
     </para>
    </listitem>
   </varlistentry>
@@ -3819,7 +4015,7 @@
    <term><parameter>header_length</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the number of quadlets in the header
     </para>
    </listitem>
   </varlistentry>
@@ -3827,7 +4023,7 @@
    <term><parameter>expect_response</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      indicate with a 0 or 1 whether to receive a completion event
     </para>
    </listitem>
   </varlistentry>
@@ -3835,7 +4031,7 @@
    <term><parameter>data</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      pointer to data to send
     </para>
    </listitem>
   </varlistentry>
@@ -3843,7 +4039,7 @@
    <term><parameter>rawtag</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      data to identify the request to completion handler
     </para>
    </listitem>
   </varlistentry>
@@ -3865,6 +4061,12 @@
    corrupt packet may lead to weird results.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -3903,7 +4105,7 @@
    <term><parameter>node</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      target node
     </para>
    </listitem>
   </varlistentry>
@@ -3911,7 +4113,7 @@
    <term><parameter>addr</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      address to read from
     </para>
    </listitem>
   </varlistentry>
@@ -3919,7 +4121,7 @@
    <term><parameter>length</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      amount of data to read in quadlets
     </para>
    </listitem>
   </varlistentry>
@@ -3927,7 +4129,7 @@
    <term><parameter>buffer</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      pointer to buffer where data will be saved
     </para>
    </listitem>
   </varlistentry>
@@ -3941,6 +4143,12 @@
    handlers called will be therefore lost.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -3979,7 +4187,7 @@
    <term><parameter>node</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      target node
     </para>
    </listitem>
   </varlistentry>
@@ -3987,7 +4195,7 @@
    <term><parameter>addr</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      address to write to
     </para>
    </listitem>
   </varlistentry>
@@ -3995,7 +4203,7 @@
    <term><parameter>length</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      amount of data to write in quadlets
     </para>
    </listitem>
   </varlistentry>
@@ -4003,7 +4211,7 @@
    <term><parameter>data</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      pointer to data to be sent
     </para>
    </listitem>
   </varlistentry>
@@ -4017,6 +4225,12 @@
    handlers called will be therefore lost.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -4057,7 +4271,7 @@
    <term><parameter>node</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      target node
     </para>
    </listitem>
   </varlistentry>
@@ -4065,7 +4279,7 @@
    <term><parameter>addr</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      address to read from
     </para>
    </listitem>
   </varlistentry>
@@ -4073,7 +4287,7 @@
    <term><parameter>extcode</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      extended transaction code determining the lock operation
     </para>
    </listitem>
   </varlistentry>
@@ -4081,7 +4295,7 @@
    <term><parameter>data</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      data part of lock parameters
     </para>
    </listitem>
   </varlistentry>
@@ -4089,7 +4303,7 @@
    <term><parameter>arg</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      arg part of lock parameters
     </para>
    </listitem>
   </varlistentry>
@@ -4097,7 +4311,7 @@
    <term><parameter>result</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      address where return value will be written
     </para>
    </listitem>
   </varlistentry>
@@ -4111,6 +4325,12 @@
    handlers called will be therefore lost.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -4151,7 +4371,7 @@
    <term><parameter>node</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      target node
     </para>
    </listitem>
   </varlistentry>
@@ -4159,7 +4379,7 @@
    <term><parameter>addr</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      address to read from
     </para>
    </listitem>
   </varlistentry>
@@ -4167,7 +4387,7 @@
    <term><parameter>extcode</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      extended transaction code determining the lock operation
     </para>
    </listitem>
   </varlistentry>
@@ -4175,7 +4395,7 @@
    <term><parameter>data</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      data part of lock parameters
     </para>
    </listitem>
   </varlistentry>
@@ -4183,7 +4403,7 @@
    <term><parameter>arg</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      arg part of lock parameters
     </para>
    </listitem>
   </varlistentry>
@@ -4191,7 +4411,7 @@
    <term><parameter>result</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      address where return value will be written
     </para>
    </listitem>
   </varlistentry>
@@ -4205,6 +4425,12 @@
    handlers called will be therefore lost.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -4244,7 +4470,7 @@
    <term><parameter>channel</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the isochronous channel number to send on
     </para>
    </listitem>
   </varlistentry>
@@ -4252,7 +4478,7 @@
    <term><parameter>tag</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      data to be put into packet's tag field
     </para>
    </listitem>
   </varlistentry>
@@ -4260,7 +4486,7 @@
    <term><parameter>sy</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      data to be put into packet's sy field
     </para>
    </listitem>
   </varlistentry>
@@ -4268,7 +4494,7 @@
    <term><parameter>speed</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      speed at which to send
     </para>
    </listitem>
   </varlistentry>
@@ -4276,7 +4502,7 @@
    <term><parameter>length</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      amount of data to send
     </para>
    </listitem>
   </varlistentry>
@@ -4284,12 +4510,18 @@
    <term><parameter>data</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      pointer to data to send
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -4327,7 +4559,7 @@
    <term><parameter>length</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the amount of quadlets of data to send
     </para>
    </listitem>
   </varlistentry>
@@ -4335,7 +4567,7 @@
    <term><parameter>header_length</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the number of quadlets in the header
     </para>
    </listitem>
   </varlistentry>
@@ -4343,7 +4575,7 @@
    <term><parameter>expect_response</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      indicate with a 0 or 1 whether to receive a completion event
     </para>
    </listitem>
   </varlistentry>
@@ -4351,12 +4583,18 @@
    <term><parameter>data</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      pointer to data to send
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -4398,6 +4636,12 @@
    callback specified with <function>raw1394_set_fcp_handler</function>.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -4437,6 +4681,12 @@
    FCP_RESPONSE address ranges) on <parameter>handle</parameter>.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    0 on success or -1 on failure (sets errno)
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -4478,6 +4728,12 @@
    Might be useful for an application.
  </para>
 </refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    a pointer to a string containing the version number
+ </para>
+</refsect1>
 </refentry>
 
 <refentry>
@@ -4487,7 +4743,7 @@
 <refnamediv>
  <refname>raw1394_update_config_rom</refname>
  <refpurpose>
-      updates the configuration rom of a host
+      updates the configuration ROM of a host
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
@@ -4515,7 +4771,7 @@
    <term><parameter>new_rom</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      a pointer to the new ROM image
     </para>
    </listitem>
   </varlistentry>
@@ -4523,7 +4779,7 @@
    <term><parameter>size</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the size of the new ROM image in quadlets
     </para>
    </listitem>
   </varlistentry>
@@ -4531,7 +4787,7 @@
    <term><parameter>rom_version</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the version numer of the current version, not the new
     </para>
    </listitem>
   </varlistentry>
@@ -4542,8 +4798,14 @@
  <para>
    <parameter>rom_version</parameter> must be the current
    version, otherwise it will fail with return value -1. 
-   Return value -2 indicates that the new rom version is too big.
-   Return value 0 indicates success
+ </para>
+</refsect1>
+<refsect1>
+ <title>Returns</title>
+ <para>
+    -1 (failure) if the version is incorrect, 
+   -2 (failure) if the new rom version is too big, or
+   0 for success
  </para>
 </refsect1>
 </refentry>
@@ -4555,7 +4817,7 @@
 <refnamediv>
  <refname>raw1394_get_config_rom</refname>
  <refpurpose>
-      reads the current version of the configuration rom of a host
+      reads the current version of the configuration ROM of a host
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
@@ -4584,7 +4846,7 @@
    <term><parameter>buffer</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      the memory address at which to store the copy of the ROM
     </para>
    </listitem>
   </varlistentry>
@@ -4600,7 +4862,7 @@
    <term><parameter>rom_size</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      upon successful return, contains the size of the ROM
     </para>
    </listitem>
   </varlistentry>
@@ -4608,7 +4870,7 @@
    <term><parameter>rom_version</parameter></term>
    <listitem>
     <para>
-     -- undescribed --
+      upon successful return, contains the version of the rom
     </para>
    </listitem>
   </varlistentry>
@@ -4619,8 +4881,12 @@
  <para>
    returns the size of the current rom image. <parameter>rom_version</parameter> is the
    version number of the fetched rom.
-   return value -1 indicates, that the buffer was too small, 
-   0 indicates success.
+ </para>
+</refsect1>
+<refsect1>
+ <title>Return</title>
+ <para>
+    -1 (failure) if the buffer was too small or 0 for success
  </para>
 </refsect1>
 </refentry>
diff --git a/src/raw1394.h b/src/raw1394.h
index 59fca94..ee6ad74 100644
--- a/src/raw1394.h
+++ b/src/raw1394.h
@@ -129,6 +129,8 @@ typedef enum raw1394_iso_disposition (*raw1394_iso_recv_handler_t)(
  * @irq_interval: maximum latency of wake-ups, in packets (-1 if you don't care)
  *
  * Allocates all user and kernel resources necessary for isochronous transmission.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_iso_xmit_init(raw1394handle_t handle,
                           raw1394_iso_xmit_handler_t handler,
@@ -151,6 +153,8 @@ int raw1394_iso_xmit_init(raw1394handle_t handle,
  * (-1 if you don't care)
  *
  * Allocates all user and kernel resources necessary for isochronous reception.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_iso_recv_init(raw1394handle_t handle,
                           raw1394_iso_recv_handler_t handler,
@@ -171,6 +175,8 @@ int raw1394_iso_recv_init(raw1394handle_t handle,
  * @irq_interval: maximum latency of wake-ups, in packets (-1 if you don't care)
  *
  * Allocates all user and kernel resources necessary for isochronous reception.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_iso_multichannel_recv_init(raw1394handle_t handle,
                                        raw1394_iso_recv_handler_t handler,
@@ -181,8 +187,11 @@ int raw1394_iso_multichannel_recv_init(raw1394handle_t handle,
 /**
  * raw1394_iso_recv_listen_channel - listen to a specific channel in multi-channel mode
  * @handle: libraw1394 handle
+ * @channel: the channel to start listening
  *
- * listen/unlisten on a specific channel (multi-channel mode ONLY)	
+ * listen/unlisten on a specific channel (multi-channel mode ONLY)
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_iso_recv_listen_channel(raw1394handle_t handle, 
                                     unsigned char channel);
@@ -190,6 +199,9 @@ int raw1394_iso_recv_listen_channel(raw1394handle_t handle,
 /**
  * raw1394_iso_recv_unlisten_channel - stop listening  to a specific channel in multi-channel mode
  * @handle: libraw1394 handle
+ * @channel: the channel to stop listening to
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_iso_recv_unlisten_channel(raw1394handle_t handle, 
                                       unsigned char channel);
@@ -201,6 +213,8 @@ int raw1394_iso_recv_unlisten_channel(raw1394handle_t handle,
  *        channel 0 is LSB, channel 63 is MSB
  *
  * for multi-channel reception mode only
+ *
+ * Returns: 0 on success, -1 on failure (sets errno)
  **/
 int raw1394_iso_recv_set_channel_mask(raw1394handle_t handle, u_int64_t mask);
 
@@ -211,6 +225,8 @@ int raw1394_iso_recv_set_channel_mask(raw1394handle_t handle, u_int64_t mask);
  * (-1 if you don't care)
  * @prebuffer_packets: number of packets to queue up before starting transmission
  * (-1 if you don't care)
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_iso_xmit_start(raw1394handle_t handle, int start_on_cycle,
                            int prebuffer_packets);
@@ -222,6 +238,8 @@ int raw1394_iso_xmit_start(raw1394handle_t handle, int start_on_cycle,
  * (-1 if you don't care)
  * @tag_mask: mask of tag fields to match (-1 to receive all packets)
  * @sync: not used, reserved for future implementation
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_iso_recv_start(raw1394handle_t handle, int start_on_cycle, 
                            int tag_mask, int sync);
@@ -238,6 +256,8 @@ int raw1394_iso_recv_start(raw1394handle_t handle, int start_on_cycle,
  * if buffer is full, waits for more space UNLESS the file descriptor is
  * set to non-blocking, in which case xmit_write() will return -1 with
  * errno = EAGAIN
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_iso_xmit_write(raw1394handle_t handle, unsigned char *data, 
                            unsigned int len, unsigned char tag, 
@@ -246,6 +266,8 @@ int raw1394_iso_xmit_write(raw1394handle_t handle, unsigned char *data,
 /**
  * raw1394_iso_xmit_sync - wait until all queued packets have been sent
  * @handle: libraw1394 handle
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_iso_xmit_sync(raw1394handle_t handle);
 
@@ -261,6 +283,8 @@ int raw1394_iso_xmit_sync(raw1394handle_t handle);
  * that there should be more packets at this moment, you can call this
  * function and all iso packets which are already received by the kernel
  * will be flushed out to user space.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_iso_recv_flush(raw1394handle_t handle);
 
@@ -287,14 +311,15 @@ typedef int raw1394_errcode_t;
  * raw1394_get_errcode - return error code of async transaction
  * @handle: libraw1394 handle
  *
- * Returns the error code of the last raw1394_read(), raw1394_write(),
+ * Some macros are available to extract information from the error code,
+ * raw1394_errcode_to_errno() can be used to convert it to an errno number of
+ * roughly the same meaning.
+ *
+ * Returns: the error code of the last raw1394_read(), raw1394_write(),
  * raw1394_lock() or raw1394_iso_write().  The error code is either an internal
  * error (i.e. not a bus error) or a combination of acknowledge code and
  * response code, as appropriate.
  *
- * Some macros are available to extract information from the error code,
- * raw1394_errcode_to_errno() can be used to convert it to an errno number of
- * roughly the same meaning.
  **/
 raw1394_errcode_t raw1394_get_errcode(raw1394handle_t handle);
 
@@ -312,7 +337,7 @@ raw1394_errcode_t raw1394_get_errcode(raw1394handle_t handle);
  * meaning only, the associated text of e.g. perror() is not necessarily
  * meaningful.
  *
- * Returned values are %EAGAIN (retrying might succeed, also generation number
+ * Returns: %EAGAIN (retrying might succeed, also generation number
  * mismatch), %EREMOTEIO (other node had internal problems), %EPERM (operation
  * not allowed on this address, e.g. write on read-only location), %EINVAL
  * (invalid argument) and %EFAULT (invalid pointer).
@@ -327,7 +352,7 @@ int raw1394_errcode_to_errno(raw1394_errcode_t errcode);
  * processes.  It is allowed to create and use multiple handles, however.  Use
  * one handle per thread which needs it in the multithreaded case.
  *
- * Returns the created handle or %NULL when initialization fails.  In the latter
+ * Returns: the created handle or %NULL when initialization fails. In the latter
  * case errno either contains some OS specific error code or %0 if the error is
  * that libraw1394 and raw1394 don't support each other's protocol versions.
  **/
@@ -352,17 +377,17 @@ void raw1394_destroy_handle(raw1394handle_t handle);
  * raw1394_get_port_info() and raw1394_set_port(). Useful for
  * command-line programs that already know what port they want. If
  * raw1394_set_port() returns ESTALE, retries automatically.
+ *
+ * Returns: the new handle on success or NULL on failure
  **/
 raw1394handle_t raw1394_new_handle_on_port(int port);
 
 /**
  * raw1394_busreset_notify - Switch off/on busreset-notification for handle
  * @handle: libraw1394 handle
+ * @off_on_switch: RAW1394_NOTIFY_OFF or RAW1394_NOTIFY_ON
  *
- * returns:
- * ==0 success 
- * !=0 failure
- * off_on_switch .... RAW1394_NOTIFY_OFF or RAW1394_NOTIFY_ON
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_busreset_notify (raw1394handle_t handle, int off_on_switch);
 
@@ -370,12 +395,13 @@ int raw1394_busreset_notify (raw1394handle_t handle, int off_on_switch);
  * raw1394_get_fd - get the communication file descriptor
  * @handle: libraw1394 handle
  *
- * Returns the fd used for communication with the raw1394 kernel module.  This
- * can be used for select()/poll() calls if you wait on other fds or can be
+ * This can be used for select()/poll() calls if you wait on other fds or can be
  * integrated into another event loop (e.g. from a GUI application framework).
  * It can also be used to set/remove the O_NONBLOCK flag using fcntl() to modify
  * the blocking behaviour in raw1394_loop_iterate().  It must not be used for
  * anything else.
+ *
+ * Returns: the fd used for communication with the raw1394 kernel module.
  **/
 int raw1394_get_fd(raw1394handle_t handle);
 
@@ -395,7 +421,7 @@ void raw1394_set_userdata(raw1394handle_t handle, void *data);
  * raw1394_get_userdata - retrieve user data from handle
  * @handle: libraw1394 handle
  *
- * Returns the user data pointer associated with the handle using
+ * Returns: the user data pointer associated with the handle using
  * raw1394_set_userdata().
  **/
 void *raw1394_get_userdata(raw1394handle_t handle);
@@ -404,7 +430,7 @@ void *raw1394_get_userdata(raw1394handle_t handle);
  * raw1394_get_local_id - get node ID of the current port
  * @handle: libraw1394 handle
  *
- * Returns the node ID of the local node connected to which the handle is
+ * Returns: the node ID of the local node connected to which the handle is
  * connected.  This value can change with every bus reset.
  **/
 nodeid_t raw1394_get_local_id(raw1394handle_t handle);
@@ -413,7 +439,7 @@ nodeid_t raw1394_get_local_id(raw1394handle_t handle);
  * raw1394_get_irm_id - get node ID of isochronous resource manager
  * @handle: libraw1394 handle
  *
- * Returns the node ID of the isochronous resource manager of the bus the handle
+ * Returns: the node ID of the isochronous resource manager of the bus the handle
  * is connected to.  This value may change with every bus reset.
  **/
 nodeid_t raw1394_get_irm_id(raw1394handle_t handle);
@@ -422,10 +448,12 @@ nodeid_t raw1394_get_irm_id(raw1394handle_t handle);
  * raw1394_get_nodecount - get number of nodes on the bus
  * @handle: libraw1394 handle
  *
- * Returns the number of nodes on the bus to which the handle is connected.
- * This value can change with every bus reset.  Since the root node always has
+ * Since the root node always has
  * the highest node ID, this number can be used to determine that ID (it's
  * LOCAL_BUS|(count-1)).
+ *
+ * Returns: the number of nodes on the bus to which the handle is connected.
+ * This value can change with every bus reset.
  **/
 int raw1394_get_nodecount(raw1394handle_t handle);
 
@@ -446,11 +474,11 @@ struct raw1394_portinfo {
  * If your program is interactive, you should present the user with this list to
  * let them decide which port to use if there is more than one.  A
  * non-interactive program (and probably interactive ones, too) should provide a
- * command line option to choose the port.
- *
- * Returns the number of ports and writes information about them into @pinf, but
- * not into more than @maxports elements.  If @maxports is %0, @pinf can be
+ * command line option to choose the port. If @maxports is %0, @pinf can be
  * %NULL, too.
+ *
+ * Returns: the number of ports and writes information about them into @pinf, but
+ * not into more than @maxports elements.
  **/
 int raw1394_get_port_info(raw1394handle_t handle, struct raw1394_portinfo *pinf,
                           int maxports);
@@ -466,7 +494,7 @@ int raw1394_get_port_info(raw1394handle_t handle, struct raw1394_portinfo *pinf,
  * To make up for this, all the other functions (those handling asynchronous and
  * isochronous transmissions) can now be called.
  *
- * Returns %0 for success and -1 for failure with errno set appropriately.  A
+ * Returns: %0 for success or -1 for failure with errno set appropriately.  A
  * possible failure mode is with errno = %ESTALE, in this case the configuration
  * has changed since the call to raw1394_get_port_info() and it has to be called
  * again to update your view of the available ports.
@@ -481,18 +509,16 @@ int raw1394_set_port(raw1394handle_t handle, int port);
  * not necessary and should be avoided, this function is here for low level bus
  * control and debugging.
  *
- * Returns: %0 for success and -1 for failure with errno set appropriately.
+ * Returns: %0 for success or -1 for failure with errno set appropriately
  **/
 int raw1394_reset_bus(raw1394handle_t handle);
 
 /**
  * raw1394_reset_bus_new - Reset the connected bus (with certain type). 
  * @handle: libraw1394 handle
+ * @type: RAW1394_SHORT_RESET or RAW1394_LONG_RESET
  *
- * returns:
- * -1 failure 
- * 0  success
- * type .... RAW1394_SHORT_RESET or RAW1394_LONG_RESET
+ * Returns: %0 for success or -1 for failure 
  **/
 int raw1394_reset_bus_new(raw1394handle_t handle, int type);
 
@@ -501,12 +527,12 @@ int raw1394_reset_bus_new(raw1394handle_t handle, int type);
  * @handle: libraw1394 handle
  *
  * Get one new message through handle and process it with the registered message
- * handler.  This function will return %-1 for an error or the return value of
- * the handler which got executed.  The default handlers always return zero.
+ * handler. Note that some other library functions may call this function 
+ * multiple times to wait for their completion, some handler return values may 
+ * get lost if you use these.
  *
- * Note that some other library functions may call this function multiple times
- * to wait for their completion, some handler return values may get lost if you
- * use these.
+ * Returns: %-1 for an error or the return value of
+ * the handler which got executed. The default handlers always return zero.
  **/
 int raw1394_loop_iterate(raw1394handle_t handle);
 
@@ -517,8 +543,10 @@ typedef int (*bus_reset_handler_t)(raw1394handle_t, unsigned int generation);
  * @handle: libraw1394 handle
  * @new_h: pointer to new handler
  *
- * Sets the handler to be called on every bus reset to @new_h and returns the
- * old handler. The default handler just calls raw1394_update_generation().
+ * Sets the handler to be called on every bus reset to @new_h.
+ * The default handler just calls raw1394_update_generation().
+ *
+ * Returns: the old handler
  **/
 bus_reset_handler_t raw1394_set_bus_reset_handler(raw1394handle_t handle,
                                                   bus_reset_handler_t new_h);
@@ -527,20 +555,20 @@ bus_reset_handler_t raw1394_set_bus_reset_handler(raw1394handle_t handle,
  * raw1394_get_generation - get generation number of handle
  * @handle: libraw1394 handle
  *
- * This function returns the generation number associated with the handle.  The
- * generation number is incremented on every bus reset, and every transaction
+ * The generation number is incremented on every bus reset, and every transaction
  * started by raw1394 is tagged with the stored generation number.  If these
  * don't match, the transaction will abort with an error.
- *
  * The generation number of the handle is not automatically updated,
  * raw1394_update_generation() has to be used for this.
+ *
+ * Returns: the generation number associated with the handle 
  **/
 unsigned int raw1394_get_generation(raw1394handle_t handle);
 
 /**
  * raw1394_update_generation - set generation number of handle
- * @generation: new generation number
  * @handle: libraw1394 handle
+ * @generation: new generation number
  *
  * This function sets the generation number of the handle to @gen.  All requests
  * that apply to a single node ID are tagged with this number and abort with an
@@ -560,14 +588,16 @@ typedef int (*tag_handler_t)(raw1394handle_t, unsigned long tag,
  * @handle: libraw1394 handle
  * @new_h: pointer to new handler
  *
- * Sets the handler to be called whenever a request completes to @new_h and
- * returns the old handler.  The default handler interprets the tag as a pointer
+ * Sets the handler to be called whenever a request completes to @new_h.
+ * The default handler interprets the tag as a pointer
  * to a &struct raw1394_reqhandle and calls the callback in there.
  *
  * Care must be taken when replacing the tag handler and calling the synchronous
  * versions of the transaction functions (i.e. raw1394_read(), raw1394_write(),
  * raw1394_lock(), raw1394_iso_write()) since these do pass pointers to &struct
  * raw1394_reqhandle as the tag and expect the callback to be invoked.
+ *
+ * Returns: the old handler
  **/
 tag_handler_t raw1394_set_tag_handler(raw1394handle_t handle,
                                       tag_handler_t new_h);
@@ -583,7 +613,9 @@ typedef int (*arm_tag_handler_t)(raw1394handle_t handle, unsigned long arm_tag,
  *
  * Set the handler that will be called when an async read/write/lock arm_request
  * arrived. The default action is to call the arm_callback in the 
- * raw1394_arm_reqhandle pointed to by arm_tag.  Returns old handler.
+ * raw1394_arm_reqhandle pointed to by arm_tag.
+ *
+ * Returns: old handler
  **/
 arm_tag_handler_t raw1394_set_arm_tag_handler(raw1394handle_t handle,
                                       arm_tag_handler_t new_h);
@@ -599,16 +631,17 @@ typedef int (*fcp_handler_t)(raw1394handle_t, nodeid_t nodeid, int response,
  * Function Control Protocol is defined in IEC 61883-1.
  *
  * Sets the handler to be called when either FCP command or FCP response
- * registers get written to @new_h and returns the old handler.  The default
- * handler does nothing.
- *
+ * registers get written to @new_h.  The default handler does nothing.
  * In order to actually get FCP events, you have to enable it with
  * raw1394_start_fcp_listen() and can stop it with raw1394_stop_fcp_listen().
+ *
+ * Returns: the old handler
  **/
 fcp_handler_t raw1394_set_fcp_handler(raw1394handle_t handle, fcp_handler_t new_h);
 
 /**
  * req_callback_t - This is the general request handler
+ * @req_callback_t: This is the general request handler
  *
  * It is used by the default tag handler
  * when a request completes, it calls the callback and passes it the data
@@ -624,6 +657,7 @@ struct raw1394_reqhandle {
 
 /**
  * arm_req_callback_t - This is the general arm-request handle
+ * @arm_req_callback_t: This is the general arm-request handle
  * @handle: libraw1394 handle
  *
  * (arm = address range mapping)
@@ -665,8 +699,8 @@ struct raw1394_arm_reqhandle {
  *                    access_rights will be ignored.
  *
  * ARM = Adress Range Mapping
- * returns:            0  ... success
- *                    <0 ... failure
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_arm_register(raw1394handle_t handle, nodeaddr_t start, 
                          size_t length, byte_t *initial_value,
@@ -680,13 +714,13 @@ int raw1394_arm_register(raw1394handle_t handle, nodeaddr_t start,
  *                    (value of start have to be the same value 
  *                    used for registering this adressrange)
  * 
- * returns:           0  ... success
- *                    <0 ... failure
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_arm_unregister(raw1394handle_t handle, nodeaddr_t start);
 
 /**
  * raw1394_arm_set_buf - set the buffer of an AdressRangeMapping
+ * @handle: libraw1394 handle
  * @start: identifies addressrange
  * @length: identifies addressrange
  * @buf: pointer to buffer
@@ -695,8 +729,7 @@ int raw1394_arm_unregister(raw1394handle_t handle, nodeaddr_t start);
  * to one ARM block in kernel memory area
  * with start offset @start.
  *
- * returns:       0  ... success
- *                <0 ... failure, and errno - error code
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_arm_set_buf (raw1394handle_t handle, nodeaddr_t start,
                          size_t length, void *buf);
@@ -712,8 +745,7 @@ int raw1394_arm_set_buf (raw1394handle_t handle, nodeaddr_t start,
  * ARM block in kernel memory area with start offset @start
  * to user memory area @buf
  *
- * returns:       0  ... success
- *                <0 ... failure, and errno - error code
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_arm_get_buf (raw1394handle_t handle, nodeaddr_t start,
                          size_t length, void *buf);
@@ -726,8 +758,8 @@ int raw1394_arm_get_buf (raw1394handle_t handle, nodeaddr_t start,
  * the driver then send back the
  * same request. raw1394_loop_iterate will return data as return value,
  * when it processes the echo. 
- * returns:       0 .... success
- *                <0 ... failure
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_echo_request(raw1394handle_t handle, quadlet_t data);
 
@@ -738,8 +770,7 @@ int raw1394_echo_request(raw1394handle_t handle, quadlet_t data);
  * (or a blocking read from the device
  * file). actually this calls raw1394_echo_request with 0 as data. 
  *
- * returns:       0 .... success
- *                <0 ... failure
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_wake_up(raw1394handle_t handle);
 
@@ -747,12 +778,24 @@ int raw1394_wake_up(raw1394handle_t handle);
 /**
  * raw1394_phy_packet_write - send physical request
  * @handle: libraw1394 handle
+ * @data: the contents of the packet
  *
  * examples of physical requests are linkon, physicalconfigurationpacket, etc.
- * returns:       0 .... success
- *                <0 ... failure
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_phy_packet_write (raw1394handle_t handle, quadlet_t data);
+
+/**
+ * raw1394_start_phy_packet_write - initiate sending a physical request
+ * @handle: libraw1394 handle
+ * @data: the contents of the packet
+ * @tag: data to identify the request to completion handler
+ *
+ * examples of physical requests are linkon, physicalconfigurationpacket, etc.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
+ **/
 int raw1394_start_phy_packet_write(raw1394handle_t handle, 
         quadlet_t data, unsigned long tag);
 
@@ -765,8 +808,7 @@ int raw1394_start_phy_packet_write(raw1394handle_t handle,
  * @buffer: pointer to buffer where data will be saved
  * @tag: data to identify the request to completion handler
  *
- * This function starts the specified read request and returns %0 for success
- * and a negative number for an error, in which case errno will be set.  If
+ * This function starts the specified read request. If
  * @length is %4 a quadlet read is initiated and a block read otherwise.
  *
  * The transaction is only started, no success of the transaction is implied
@@ -775,6 +817,8 @@ int raw1394_start_phy_packet_write(raw1394handle_t handle,
  * error code of the transaction.  @tag should therefore be set to something
  * that uniquely identifies this transaction (e.g. a struct pointer casted to
  * unsigned long).
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_start_read(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                        size_t length, quadlet_t *buffer, unsigned long tag);
@@ -788,8 +832,7 @@ int raw1394_start_read(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
  * @data: pointer to data to be sent
  * @tag: data to identify the request to completion handler
  *
- * This function starts the specified write request and returns %0 for success
- * and a negative number for an error, in which case errno will be set.  If
+ * This function starts the specified write request. If
  * @length is %4 a quadlet write is initiated and a block write otherwise.
  *
  * The transaction is only started, no success of the transaction is implied
@@ -798,6 +841,8 @@ int raw1394_start_read(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
  * error code of the transaction.  @tag should therefore be set to something
  * that uniquely identifies this transaction (e.g. a struct pointer casted to
  * unsigned long).
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_start_write(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                         size_t length, quadlet_t *data, unsigned long tag);
@@ -813,15 +858,15 @@ int raw1394_start_write(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
  * @result: address where return value will be written
  * @tag: data to identify the request to completion handler
  *
- * This function starts the specified lock request and returns %0 for success
- * and a negative number for an error, in which case errno will be set.
- *
+ * This function starts the specified lock request.
  * The transaction is only started, no success of the transaction is implied
  * with a successful return of this function.  When the transaction completes, a
  * raw1394_loop_iterate() will call the tag handler and pass it the tag and
  * error code of the transaction.  @tag should therefore be set to something
  * that uniquely identifies this transaction (e.g. a struct pointer casted to
  * unsigned long).
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_start_lock(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                        unsigned int extcode, quadlet_t data, quadlet_t arg,
@@ -838,15 +883,15 @@ int raw1394_start_lock(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
  * @result: address where return value will be written
  * @tag: data to identify the request to completion handler
  *
- * This function starts the specified lock request and returns %0 for success
- * and a negative number for an error, in which case errno will be set.
- *
+ * This function starts the specified lock request.
  * The transaction is only started, no success of the transaction is implied
  * with a successful return of this function.  When the transaction completes, a
  * raw1394_loop_iterate() will call the tag handler and pass it the tag and
  * error code of the transaction.  @tag should therefore be set to something
  * that uniquely identifies this transaction (e.g. a struct pointer casted to
  * unsigned long).
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_start_lock64(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                        unsigned int extcode, octlet_t data, octlet_t arg,
@@ -855,9 +900,18 @@ int raw1394_start_lock64(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
 /**
  * raw1394_start_read - initiate asynchronous stream
  * @handle: libraw1394 handle
+ * @channel: the isochronous channel number to send on
+ * @tag: data to be put into packet's tag field
+ * @sy: data to be put into packet's sy field
+ * @speed: speed at which to send
+ * @length: amount of data to send
+ * @data: pointer to data to send
+ * @rawtag: data to identify the request to completion handler
  *
  * Passes custom tag.  Use pointer to raw1394_reqhandle if you use the standard
  * tag handler.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_start_async_stream(raw1394handle_t handle, unsigned int channel,
                                unsigned int tag, unsigned int sy,
@@ -868,6 +922,11 @@ int raw1394_start_async_stream(raw1394handle_t handle, unsigned int channel,
 /**
  * raw1394_start_async_send - send an asynchronous packet
  * @handle: libraw1394 handle
+ * @length: the amount of quadlets of data to send
+ * @header_length: the number of quadlets in the header
+ * @expect_response: indicate with a 0 or 1 whether to receive a completion event
+ * @data: pointer to data to send
+ * @rawtag: data to identify the request to completion handler
  *
  * This starts sending an arbitrary async packet. It gets an array of quadlets 
  * consisting of header and data (without CRC in between). Header information 
@@ -880,6 +939,8 @@ int raw1394_start_async_stream(raw1394handle_t handle, unsigned int channel,
  * transactions, that are handled by the application.
  * Do not use that function, unless you really know, what you do! Sending 
  * corrupt packet may lead to weird results.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_start_async_send(raw1394handle_t handle,
                              size_t length, size_t header_length, 
@@ -889,10 +950,16 @@ int raw1394_start_async_send(raw1394handle_t handle,
 /**
  * raw1394_read - send async read request to a node and wait for response.
  * @handle: libraw1394 handle
+ * @node: target node
+ * @addr: address to read from
+ * @length: amount of data to read in quadlets
+ * @buffer: pointer to buffer where data will be saved
  *
  * This does the complete transaction and will return when it's finished.  It
  * will call raw1394_loop_iterate() as often as necessary, return values of
  * handlers called will be therefore lost.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_read(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                  size_t length, quadlet_t *buffer);
@@ -900,10 +967,16 @@ int raw1394_read(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
 /**
  * raw1394_write - send async write request to a node and wait for response.
  * @handle: libraw1394 handle
+ * @node: target node
+ * @addr: address to write to
+ * @length: amount of data to write in quadlets
+ * @data: pointer to data to be sent
  *
  * This does the complete transaction and will return when it's finished.  It
  * will call raw1394_loop_iterate() as often as necessary, return values of
  * handlers called will be therefore lost.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_write(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                   size_t length, quadlet_t *data);
@@ -911,10 +984,18 @@ int raw1394_write(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
 /**
  * raw1394_lock - send 32-bit compare-swap lock request and wait for response.
  * @handle: libraw1394 handle
+ * @node: target node
+ * @addr: address to read from
+ * @extcode: extended transaction code determining the lock operation
+ * @data: data part of lock parameters
+ * @arg: arg part of lock parameters
+ * @result: address where return value will be written
  *
  * This does the complete transaction and will return when it's finished.  It
  * will call raw1394_loop_iterate() as often as necessary, return values of
  * handlers called will be therefore lost.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_lock(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                  unsigned int extcode, quadlet_t data, quadlet_t arg,
@@ -923,10 +1004,18 @@ int raw1394_lock(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
 /**
  * raw1394_lock64 - send 64-bit compare-swap lock request and wait for response.
  * @handle: libraw1394 handle
+ * @node: target node
+ * @addr: address to read from
+ * @extcode: extended transaction code determining the lock operation
+ * @data: data part of lock parameters
+ * @arg: arg part of lock parameters
+ * @result: address where return value will be written
  *
  * This does the complete transaction and will return when it's finished.  It
  * will call raw1394_loop_iterate() as often as necessary, return values of
  * handlers called will be therefore lost.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_lock64(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
                  unsigned int extcode, octlet_t data, octlet_t arg,
@@ -935,6 +1024,14 @@ int raw1394_lock64(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
 /**
  * raw1394_async_stream
  * @handle: libraw1394 handle
+ * @channel: the isochronous channel number to send on
+ * @tag: data to be put into packet's tag field
+ * @sy: data to be put into packet's sy field
+ * @speed: speed at which to send
+ * @length: amount of data to send
+ * @data: pointer to data to send
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_async_stream(raw1394handle_t handle, unsigned int channel,
                          unsigned int tag, unsigned int sy, unsigned int speed,
@@ -943,6 +1040,12 @@ int raw1394_async_stream(raw1394handle_t handle, unsigned int channel,
 /**
  * raw1394_async_send
  * @handle: libraw1394 handle
+ * @length: the amount of quadlets of data to send
+ * @header_length: the number of quadlets in the header
+ * @expect_response: indicate with a 0 or 1 whether to receive a completion event
+ * @data: pointer to data to send
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_async_send(raw1394handle_t handle,
                        size_t length, size_t header_length,
@@ -957,6 +1060,8 @@ int raw1394_async_send(raw1394handle_t handle,
  * Enables the reception of FCP events (writes to the FCP_COMMAND or
  * FCP_RESPONSE address ranges) on @handle.  FCP requests are then passed to the
  * callback specified with raw1394_set_fcp_handler().
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_start_fcp_listen(raw1394handle_t handle);
 
@@ -966,6 +1071,8 @@ int raw1394_start_fcp_listen(raw1394handle_t handle);
  *
  * Stops the reception of FCP events (writes to the FCP_COMMAND or
  * FCP_RESPONSE address ranges) on @handle.
+ *
+ * Returns: 0 on success or -1 on failure (sets errno)
  **/
 int raw1394_stop_fcp_listen(raw1394handle_t handle);
 
@@ -975,18 +1082,25 @@ int raw1394_stop_fcp_listen(raw1394handle_t handle);
  *
  * Instead, typically, one uses 'pkg-config --mod-version libraw1394'
  * Might be useful for an application.
+ *
+ * Returns: a pointer to a string containing the version number
  */
 const char *raw1394_get_libversion(void);
 
 
 /**
- * raw1394_update_config_rom - updates the configuration rom of a host
+ * raw1394_update_config_rom - updates the configuration ROM of a host
  * @handle: libraw1394 handle
+ * @new_rom: a pointer to the new ROM image
+ * @size: the size of the new ROM image in quadlets
+ * @rom_version: the version numer of the current version, not the new
  *
  * @rom_version must be the current
  * version, otherwise it will fail with return value -1. 
- * Return value -2 indicates that the new rom version is too big.
- * Return value 0 indicates success
+ *
+ * Returns: -1 (failure) if the version is incorrect, 
+ * -2 (failure) if the new rom version is too big, or
+ * 0 for success
  **/
 
 int raw1394_update_config_rom(raw1394handle_t handle, const quadlet_t
@@ -994,14 +1108,17 @@ int raw1394_update_config_rom(raw1394handle_t handle, const quadlet_t
 
 
 /**
- * raw1394_get_config_rom - reads the current version of the configuration rom of a host
+ * raw1394_get_config_rom - reads the current version of the configuration ROM of a host
  * @handle: libraw1394 handle
+ * @buffer: the memory address at which to store the copy of the ROM
  * @buffersize: is the size of the buffer, @rom_size
+ * @rom_size: upon successful return, contains the size of the ROM
+ * @rom_version: upon successful return, contains the version of the rom
  *
  * returns the size of the current rom image. @rom_version is the
  * version number of the fetched rom.
- * return value -1 indicates, that the buffer was too small, 
- * 0 indicates success.
+ *
+ * Return: -1 (failure) if the buffer was too small or 0 for success
  **/
 
 int raw1394_get_config_rom(raw1394handle_t handle, quadlet_t *buffer,