From: Peter Meerwald <pmeerw@pmeerw.net>
Date: Sun, 8 Jan 2012 10:13:37 +0000 (+0100)
Subject: pulse: Document general error handling.
X-Git-Tag: 1.0_branch~122
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=2da8b1fa63dc23648e9b3f5cc41a62bd9539b4cd;p=profile%2Fivi%2Fpulseaudio.git

pulse: Document general error handling.
---

diff --git a/src/pulse/pulseaudio.h b/src/pulse/pulseaudio.h
index bb71772..21b7213 100644
--- a/src/pulse/pulseaudio.h
+++ b/src/pulse/pulseaudio.h
@@ -105,6 +105,27 @@
  * to make sure event objects are not manipulated when any other code is
  * using the main loop.
  *
+ * \section error_sec Error Handling
+ *
+ * Every function should explicitly document how errors are reported to
+ * the caller. Unfortunately, currently a lot of that documentation is
+ * missing. Here is an overview of the general conventions used.
+ *
+ * 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