NEWS: Add most important items since last release.

[libsigrok.git] / error.c

diff --git a/error.c b/error.c
index d0697bc84e84fda1f9e4046ab317176bbd1d4c88..d7d792d53bd5f8c6c7dd53170c723648404a8e97 100644 (file)
--- a/error.c
+++ b/error.c
@@ -1,5 +1,5 @@
 /*
- * This file is part of the sigrok project.
+ * This file is part of the libsigrok project.
  *
  * Copyright (C) 2012 Uwe Hermann <uwe@hermann-uwe.de>
  *
@@ -20,21 +20,42 @@
 
 #include "libsigrok.h"
 
+/**
+ * @file
+ *
+ * Error handling in libsigrok.
+ */
+
+/**
+ * @defgroup grp_error Error handling
+ *
+ * Error handling in libsigrok.
+ *
+ * libsigrok functions usually return @ref SR_OK upon success, or a negative
+ * error code on failure.
+ *
+ * @{
+ */
+
 /**
  * Return a human-readable error string for the given libsigrok error code.
  *
  * @param error_code A libsigrok error code number, such as SR_ERR_MALLOC.
+ *
  * @return A const string containing a short, human-readable (English)
  *         description of the error, such as "memory allocation error".
  *         The string must NOT be free'd by the caller!
+ *
  * @see sr_strerror_name
+ *
+ * @since 0.2.0
  */
 SR_API const char *sr_strerror(int error_code)
 {
        const char *str;
 
        /*
-        * Note: All defined SR_* error macros from libsigrok.h should have
+        * Note: All defined SR_* error macros from libsigrok.h must have
         * an entry in this function, as well as in sr_strerror_name().
         */
 
@@ -48,12 +69,21 @@ SR_API const char *sr_strerror(int error_code)
        case SR_ERR_MALLOC:
                str = "memory allocation error";
                break;
+       case SR_ERR_ARG:
+               str = "invalid argument";
+               break;
        case SR_ERR_BUG:
                str = "internal error";
                break;
        case SR_ERR_SAMPLERATE:
                str = "invalid samplerate";
                break;
+       case SR_ERR_NA:
+               str = "not applicable";
+               break;
+       case SR_ERR_DEV_CLOSED:
+               str = "device closed but should be open";
+               break;
        default:
                str = "unknown error";
                break;
@@ -72,16 +102,20 @@ SR_API const char *sr_strerror(int error_code)
  * a libsigrok error code is useful.
  *
  * @param error_code A libsigrok error code number, such as SR_ERR_MALLOC.
+ *
  * @return A const string containing the "name" of the error code as string.
  *         The string must NOT be free'd by the caller!
+ *
  * @see sr_strerror
+ *
+ * @since 0.2.0
  */
 SR_API const char *sr_strerror_name(int error_code)
 {
        const char *str;
 
        /*
-        * Note: All defined SR_* error macros from libsigrok.h should have
+        * Note: All defined SR_* error macros from libsigrok.h must have
         * an entry in this function, as well as in sr_strerror().
         */
 
@@ -95,12 +129,21 @@ SR_API const char *sr_strerror_name(int error_code)
        case SR_ERR_MALLOC:
                str = "SR_ERR_MALLOC";
                break;
+       case SR_ERR_ARG:
+               str = "SR_ERR_ARG";
+               break;
        case SR_ERR_BUG:
                str = "SR_ERR_BUG";
                break;
        case SR_ERR_SAMPLERATE:
                str = "SR_ERR_SAMPLERATE";
                break;
+       case SR_ERR_NA:
+               str = "SR_ERR_NA";
+               break;
+       case SR_ERR_DEV_CLOSED:
+               str = "SR_ERR_DEV_CLOSED";
+               break;
        default:
                str = "unknown error code";
                break;
@@ -108,3 +151,5 @@ SR_API const char *sr_strerror_name(int error_code)
 
        return str;
 }
+
+/** @} */