[pulseaudio-discuss] [PATCH v2] simple: Improve pa_simple_read() documentation

[Tanu Kaskinen]

On Fri, 2013-10-04 at 13:39 +0300, Tanu Kaskinen wrote:
> From: Tanu Kaskinen <tanuk at iki.fi>
> 
> There was a question in IRC about whether pa_simple_read() blocks or
> not. It's already documented on the simple API overview page, but it's
> good to say it also in the function reference. As a bonus, I added
> some additional details to the documentation too.
> ---
>  src/pulse/simple.h | 13 +++++++++++--
>  1 file changed, 11 insertions(+), 2 deletions(-)
> 
> diff --git a/src/pulse/simple.h b/src/pulse/simple.h
> index 0fab8ee..2224766 100644
> --- a/src/pulse/simple.h
> +++ b/src/pulse/simple.h
> @@ -137,8 +137,17 @@ int pa_simple_write(pa_simple *s, const void *data, size_t bytes, int *error);
>  /** Wait until all data already written is played by the daemon. */
>  int pa_simple_drain(pa_simple *s, int *error);
>  
> -/** Read some data from the server. */
> -int pa_simple_read(pa_simple *s, void *data, size_t bytes, int *error);
> +/** Read some data from the server. This function blocks until \a bytes amount
> + * of data has been received from the server, or until an error occurs.
> + * Returns a negative value on failure. */
> +int pa_simple_read(
> +    pa_simple *s, /**< The connection object. */
> +    void *data,   /**< A pointer to a buffer. */
> +    size_t bytes, /**< The number of bytes to read. */
> +    int *error
> +    /**< A pointer where the error code is stored when the function returns
> +     * a negative value. It is OK to pass NULL here. */
> +    );
>  
>  /** Return the playback latency. */
>  pa_usec_t pa_simple_get_latency(pa_simple *s, int *error);

Applied.

-- 
Tanu