Add kernel-doc style documentation headers for most exported functions.

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

1 files changed, 83 insertions, 1 deletions

diff --git a/src/readwrite.c b/src/readwrite.c
index c4a571b..bb918d4 100644
--- a/src/readwrite.c
+++ b/src/readwrite.c
@@ -1,7 +1,7 @@
 /*
  * libraw1394 - library for raw access to the 1394 bus with the Linux subsystem.
  *
- * Copyright (C) 1999,2000 Andreas Bombe
+ * Copyright (C) 1999,2000,2001,2002 Andreas Bombe
  *
  * This library is licensed under the GNU Lesser General Public License (LGPL),
  * version 2.1 or later. See the file COPYING.LIB in the distribution for
@@ -17,6 +17,25 @@
 #include "raw1394_private.h"
 
 
+/**
+ * raw1394_start_read - initiate a read transaction
+ * @node: target node
+ * @addr: address to read from
+ * @length: amount of data to read
+ * @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
+ * @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
+ * 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).
+ **/
 int raw1394_start_read(struct raw1394_handle *handle, nodeid_t node,
                        nodeaddr_t addr, size_t length, quadlet_t *buffer,
                        unsigned long tag)
@@ -36,6 +55,26 @@ int raw1394_start_read(struct raw1394_handle *handle, nodeid_t node,
         return (int)write(handle->fd, req, sizeof(*req));
 }
 
+
+/**
+ * raw1394_start_write - initiate a write transaction
+ * @node: target node
+ * @addr: address to write to
+ * @length: amount of data to write
+ * @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
+ * @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
+ * 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).
+ **/
 int raw1394_start_write(struct raw1394_handle *handle, nodeid_t node,
                         nodeaddr_t addr, size_t length, quadlet_t *data,
                         unsigned long tag)
@@ -55,6 +94,27 @@ int raw1394_start_write(struct raw1394_handle *handle, nodeid_t node,
         return (int)write(handle->fd, req, sizeof(*req));
 }
 
+
+/**
+ * raw1394_start_read - initiate a lock transaction
+ * @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
+ * @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.
+ *
+ * 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).
+ **/
 int raw1394_start_lock(struct raw1394_handle *handle, nodeid_t node,
                        nodeaddr_t addr, unsigned int extcode, quadlet_t data,
                        quadlet_t arg, quadlet_t *result, unsigned long tag)
@@ -94,6 +154,28 @@ int raw1394_start_lock(struct raw1394_handle *handle, nodeid_t node,
         return (int)write(handle->fd, req, sizeof(*req));
 }
 
+
+/**
+ * raw1394_start_iso_write - initiate an isochronous packet write
+ * @channel: channel number on which 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
+ *
+ * This function starts the specified isochronous packet transmission and
+ * returns %0 for success and a negative number for an error, in which case
+ * errno will be set.
+ *
+ * When the send 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).
+ *
+ * Isochronous packets are automatically
+ **/
 int raw1394_start_iso_write(struct raw1394_handle *handle, unsigned int channel,
                             unsigned int tag, unsigned int sy,
                             unsigned int speed, size_t length, quadlet_t *data,