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, 33 insertions, 1 deletions

diff --git a/src/errors.c b/src/errors.c
index 08ce425..e5f1af4 100644
--- a/src/errors.c
+++ b/src/errors.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
@@ -16,11 +16,43 @@
 #include "raw1394_private.h"
 #include "ieee1394.h"
 
+
+/**
+ * raw1394_get_errcode - return error code of async transaction
+ *
+ * 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(struct raw1394_handle *handle)
 {
         return handle->err;
 }
 
+/**
+ * raw1394_errcode_to_errno - convert libraw1394 errcode to errno
+ * @errcode: the error code to convert
+ *
+ * The error code as retrieved by raw1394_get_errcode() is converted into a
+ * roughly equivalent errno number and returned.  %0xdead is returned for an
+ * illegal errcode.
+ *
+ * It is intended to be used to decide what to do (retry, give up, report error)
+ * for those programs that aren't interested in details, since these get lost in
+ * the conversion.  However the returned errnos are equivalent in source code
+ * meaning only, the associated text of e.g. perror() is not necessarily
+ * meaningful.
+ *
+ * Returned values are %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).
+ **/
 int raw1394_errcode_to_errno(raw1394_errcode_t errcode)
 {
         static const int ack2errno[16] = {