[pulseaudio-discuss] [PATCH] add section about error handling to doxygen documentation

[Tanu Kaskinen]

On Mon, 2011-12-12 at 10:59 +0100, Peter Meerwald wrote:
> From: Peter Meerwald <p.meerwald at bct-electronic.com>
> 
> ---
>  src/pulse/pulseaudio.h |    8 ++++++++
>  1 files changed, 8 insertions(+), 0 deletions(-)
> 
> diff --git a/src/pulse/pulseaudio.h b/src/pulse/pulseaudio.h
> index bb71772..a368018 100644
> --- a/src/pulse/pulseaudio.h
> +++ b/src/pulse/pulseaudio.h
> @@ -105,6 +105,14 @@
>   * 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 an integer
> + * value -1 or a NULL pointer. On success, an integer value 0 or a valid
> + * pointer is returned. Certain function provide an optional error code
> + * (see #pa_error_code) which can be turned into a human readable message
> + * using pa_strerror().

This text promises too much about the return codes. Yes, -1 and 0 are
the most common values, but the numbers shouldn't be hardcoded in the
user code ("user" as in API user). A negative return code means failure
and non-negative means success, thus the user should always use "< 0" or
">= 0" to check for failure/success. If there is a special meaning
attached to some individual numbers, that will be documented separately.

Another thing is the question of when pa_strerror() can be used. That
should be documented unambiguously. I don't know what the current
situation is - my guess would be that the documentation is lacking in
this regard.

I think this text should either say what it says now, or that
pa_strerror() can be used always unless otherwise stated. Which one is
the right choice depends on which is more common, those error codes that
can be passed to pa_strerror() or those that can't (I haven't checked
what is the situation).

Regardless of what is the current situation, I think it would make sense
to guarantee every error code in the public API to be suitable to be
passed to pa_strerror().

-- 
Tanu