[pulseaudio-discuss] [PATCH v2] document general error handling

[Peter Meerwald]

changes:
* address comment regarding zero value (John Haxby)

---
 src/pulse/def.h        |    7 +++++--
 src/pulse/pulseaudio.h |   17 +++++++++++++++++
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/src/pulse/def.h b/src/pulse/def.h
index 98d3651..cfce95c 100644
--- a/src/pulse/def.h
+++ b/src/pulse/def.h
@@ -398,8 +398,11 @@ typedef struct pa_buffer_attr {
 
 } pa_buffer_attr;
 
-/** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */
-enum {
+/** Error values as returned by functions of the \ref async and
+  * pa_context_errno(), and the \ref simple.
+  *
+  * Use pa_strerror() to convert these values to human readable strings. */
+enum pa_error_code {
     PA_OK = 0,                     /**< No error */
     PA_ERR_ACCESS,                 /**< Access failure */
     PA_ERR_COMMAND,                /**< Unknown command */
diff --git a/src/pulse/pulseaudio.h b/src/pulse/pulseaudio.h
index bb71772..74a0cc1 100644
--- a/src/pulse/pulseaudio.h
+++ b/src/pulse/pulseaudio.h
@@ -105,6 +105,23 @@
  * to make sure event objects are not manipulated when any other code is
  * using the main loop.
  *
+ * \section error_sec Error Handling
+ *
+ * The PulseAudio API indicates error conditions by returning a negative
+ * integer value or a NULL pointer. On success, zero or a positive integer
+ * value or a valid pointer is returned.
+ *
+ * Functions of the \ref simple generally return -1 or NULL on failure and
+ * can optionally store an error code (see ::pa_error_code) using a pointer
+ * argument.
+ *
+ * Functions of the \ref async return an negative error code or NULL on
+ * failure (see ::pa_error_code). In the later case, pa_context_errno()
+ * can be used to obtain the error code of the last failed operation.
+ *
+ * An error code can be turned into a human readable message using
+ * pa_strerror().
+ *
  * \section pkgconfig pkg-config
  *
  * The PulseAudio libraries provide pkg-config snippets for the different
-- 
1.7.8.2