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

[Arun Raghavan]

Pushed out this wording after an IRC ack from Tanu.

On 12 January 2016 at 08:35, Arun Raghavan <arun at accosted.net> 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