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

[Colin Guthrie]

'Twas brillig, and Peter Meerwald at 12/12/11 15:48 did gyre and gimble:
> Hello Tanu,
> 
>>> I fully agree, this sounds sensible
>>> I don't see a reason to have error codes as int and not enums -- but I 
>>> guess that would be a too bit change at the moment
> 
>> A couple of reasons come to mind (I don't know the original reasoning):
>>  * In cases where a function can return either a negative or positive
>> number, using pa_error_code_t would not be the correct type for the
>> positive value (ie. not error). And actually, since pa_error_code_t
>> values are non-negative, it would be an incorrect type also for
>> functions that return the errors as negative numbers.
> 
> well, there is return code and there is error code
> 
> one way to clean up and make explicit what kind of values are allowed 
> would be to change
> 
> int foo(int *error); 
> to
> int foo(pa_error_code_t *error);
> 
> return code stays the same, error code changes from int to pa_error_code_t
> 
> obviously, functions such as pa_context_errno() would need to change...
> 
> I am not pushing this change for the moment

I don't think there is any need for this. As Tanu said, the error code
(which is very often the return code too: i.e. int foo(void);) is quite
commonly an int in C coding so I don't think there is any need to change
things.

I've not looked through the API thoroughly to see which functions have
an error point vs. their return value, but in the case where the error
code is also the return value, if your suggestion above is to be put
into action it would also be a matter of changing:
 int foo();
to
 pa_error_code_t foo();

And unless pa_error_code_t is basically a typedef or a define to int,
this would result in massive ABI/API breakage which is clearly something
that absolutely must be avoided (at least in the near future - any such
breakages would only be undertaken with very strong justification).


There are a couple places where pointers to arrays were used rather than
a pointer to a pointer which has ABI related problems (David ran into
that one), but such is life.


And the enum problem Tanu pointed out is theoretically a problem, but
I'm not sure if it's a practical one? I don't remember any specific
issues arising from when these have been extended in the past (if they
even have been extended?). Perhaps they are only used for enums that
simply will not be extended or have not yet been extended? I've not
looked at the code to double check any of this, so please take with a
pinch or salt!

Col


-- 

Colin Guthrie
gmane(at)colin.guthr.ie
http://colin.guthr.ie/

Day Job:
  Tribalogic Limited http://www.tribalogic.net/
Open Source:
  Mageia Contributor http://www.mageia.org/
  PulseAudio Hacker http://www.pulseaudio.org/
  Trac Hacker http://trac.edgewall.org/