[pulseaudio-commits] src/pulse

[Tanu Kaskinen]

 src/pulse/pulseaudio.h |   21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

New commits:
commit 2da8b1fa63dc23648e9b3f5cc41a62bd9539b4cd
Author: Peter Meerwald <pmeerw at pmeerw.net>
Date:   Sun Jan 8 11:13:37 2012 +0100

    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