I have started to go through all functions in the public API (currently 359 functions - this will take some time), prompted by the discussion that started from this patch: http://lists.freedesktop.org/archives/pulseaudio-discuss/2011-December/012412.html Instead of waiting until I'm finished with all patches, I'll send the first patches already now in case there are comments regarding the overall goals. I intend to make sure that each function documents how (non-programmer) errors are reported to the caller. I also intend to make sure that no function in the public API returns a generic -1 as the return value to represent error (unless explicitly documented). When errors are reported using a negative number, the number should be suitable for passing to pa_strerror(). pa_strerror() maps -1 to "Access denied", which usually is very misleading. Do people want me to submit each "Document pa_foo() error handling" patch separately, or should I squash them together when I'm done? Tanu Kaskinen (4): channelmap: Document pa_channel_map_parse() error handling. channelmap: Document pa_channel_position_from_string() error handling. context: Always return a valid error code from pa_context_connect() on failure. context: Document pa_context_connect() error handling. src/pulse/channelmap.h | 5 +++-- src/pulse/context.c | 19 +++++++++++++++---- src/pulse/context.h | 19 ++++++++++++------- 3 files changed, 30 insertions(+), 13 deletions(-) -- 1.7.7.3
