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
