[pulseaudio-discuss] [PATCH] stream: fix incorrect doc for pa_stream_writable_size()

[David Henningsson]

I like Arun's version better, but I'm not too fuzzed.

On 2016-01-12 04:05, Arun Raghavan wrote:
> On 11 January 2016 at 18:58, Tanu Kaskinen <tanuk at iki.fi> wrote:
>> The old documentation implied that it wouldn't be possible to write
>> more than the returned amount, which was incorrect.
>> ---
>>   src/pulse/stream.h | 9 ++++++++-
>>   1 file changed, 8 insertions(+), 1 deletion(-)
>>
>> diff --git a/src/pulse/stream.h b/src/pulse/stream.h
>> index 70fa415..802660d 100644
>> --- a/src/pulse/stream.h
>> +++ b/src/pulse/stream.h
>> @@ -588,7 +588,14 @@ int pa_stream_peek(
>>    * calling pa_stream_peek(). */
>>   int pa_stream_drop(pa_stream *p);
>>
>> -/** Return the number of bytes that may be written using pa_stream_write(). */
>> +/** Return the number of bytes that the server has requested to be written.
>> + *
>> + * Contrary to what might be expected from the function name, it's usually
>> + * possible to write more than the returned amount, but typically it doesn't
>> + * make sense to do that, because that will likely make the stream latency
>> + * exceed the target latency (which is configured with the tlength parameter in
>> + * pa_buffer_attr).
>> + */
>>   size_t pa_stream_writable_size(pa_stream *p);
>>
>>   /** Return the number of bytes that may be read using pa_stream_peek(). */
>> --
>
> I would rewrite this as:
>
> "
> Return the number of bytes requested by the server that have not yet
> been written.
>
> It is possible to write more than this amount, up to the stream's
> buffer_attr.maxlength bytes. This is usually not desirable, though, as
> it would increase stream latency to be higher than requested
> (buffer_attr.tlength).
> "
>
> -- Arun
> _______________________________________________
> pulseaudio-discuss mailing list
> pulseaudio-discuss at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/pulseaudio-discuss
>

-- 
David Henningsson, Canonical Ltd.
https://launchpad.net/~diwic