From 2da8b1fa63dc23648e9b3f5cc41a62bd9539b4cd Mon Sep 17 00:00:00 2001 From: Peter Meerwald Date: Sun, 8 Jan 2012 11:13:37 +0100 Subject: [PATCH] pulse: Document general error handling. --- src/pulse/pulseaudio.h | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) 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 -- 2.7.4