[pulseaudio-discuss] [PATCH] doc: Some more nitpicking in pulse/def.h doxygen documentation

[David Henningsson]

I pushed most of the patch but skipped a section, see below.

On 04/10/2013 06:59 PM, Peter Meerwald wrote:
> From: Peter Meerwald <p.meerwald at bct-electronic.com>
>
> Signed-off-by: Peter Meerwald <p.meerwald at bct-electronic.com>
> ---
>   src/pulse/def.h |   22 +++++++++++-----------
>   1 file changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/src/pulse/def.h b/src/pulse/def.h
> index f00253e..b507a44 100644
> --- a/src/pulse/def.h
> +++ b/src/pulse/def.h
> @@ -96,7 +96,7 @@ typedef enum pa_operation_state {
>       PA_OPERATION_RUNNING,
>       /**< The operation is still running */
>       PA_OPERATION_DONE,
> -    /**< The operation has been completed */
> +    /**< The operation has completed */
>       PA_OPERATION_CANCELLED
>       /**< The operation has been cancelled. Operations may get cancelled by the
>        * application, or as a result of the context getting disconneted while the
> @@ -130,7 +130,7 @@ typedef enum pa_context_flags {
>   /** \endcond */
>
>   /** Direction bitfield - while we currently do not expose anything bidirectional,
> -  one should test against the bit instead of the value (e g if (d & PA_DIRECTION_OUTPUT)),
> +  one should test against the bit instead of the value (e.g.\ if (d & PA_DIRECTION_OUTPUT)),
>     because we might add bidirectional stuff in the future. \since 2.0
>   */
>   typedef enum pa_direction {

I skipped the section below...

> @@ -613,20 +613,20 @@ typedef enum pa_subscription_event_type {
>    * pa_stream_update_timing_info() and pa_stream_get_timing_info(). The
>    * total output latency a sample that is written with
>    * pa_stream_write() takes to be played may be estimated by
> - * sink_usec+buffer_usec+transport_usec. (where buffer_usec is defined
> - * as pa_bytes_to_usec(write_index-read_index)) The output buffer
> + * sink_usec+buffer_usec+transport_usec (where buffer_usec is defined
> + * as pa_bytes_to_usec(write_index-read_index)). The output buffer
>    * which buffer_usec relates to may be manipulated freely (with
>    * pa_stream_write()'s seek argument, pa_stream_flush() and friends),
>    * the buffers sink_usec and source_usec relate to are first-in
>    * first-out (FIFO) buffers which cannot be flushed or manipulated in
>    * any way. The total input latency a sample that is recorded takes to
>    * be delivered to the application is:
> - * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of
> - * sign issues!) When connected to a monitor source sink_usec contains
> + * source_usec+buffer_usec+transport_usec-sink_usec (Take care of
> + * sign issues!). When connected to a monitor source sink_usec contains

...because this seemed bad. "!)." looks weird and Take should be lowercase.

>    * the latency of the owning sink. The two latency estimations
>    * described here are implemented in pa_stream_get_latency(). Please
>    * note that this structure can be extended as part of evolutionary
> - * API updates at any time in any new release.*/
> + * API updates at any time in any new release. */
>   typedef struct pa_timing_info {
>       struct timeval timestamp;
>       /**< The time when this timing info structure was current */
> @@ -771,7 +771,7 @@ typedef enum pa_sink_flags {
>        * \since 0.9.11 */
>
>       PA_SINK_FLAT_VOLUME = 0x0040U,
> -    /**< This sink is in flat volume mode, i.e. always the maximum of
> +    /**< This sink is in flat volume mode, i.e.\ always the maximum of
>        * the volume of all connected inputs. \since 0.9.15 */
>
>       PA_SINK_DYNAMIC_LATENCY = 0x0080U,
> @@ -899,7 +899,7 @@ typedef enum pa_source_flags {
>        * needs of the connected streams. \since 0.9.15 */
>
>       PA_SOURCE_FLAT_VOLUME = 0x0080U,
> -    /**< This source is in flat volume mode, i.e. always the maximum of
> +    /**< This source is in flat volume mode, i.e.\ always the maximum of
>        * the volume of all connected outputs. \since 1.0 */
>
>   #ifdef __INCLUDED_FROM_PULSE_AUDIO
> @@ -987,7 +987,7 @@ typedef void (*pa_free_cb_t)(void *p);
>
>   /** A stream policy/meta event requesting that an application should
>    * cork a specific stream. See pa_stream_event_cb_t for more
> - * information, \since 0.9.15 */
> + * information. \since 0.9.15 */
>   #define PA_STREAM_EVENT_REQUEST_CORK "request-cork"
>
>   /** A stream policy/meta event requesting that an application should
> @@ -999,7 +999,7 @@ typedef void (*pa_free_cb_t)(void *p);
>    * disconnected because the underlying sink changed and no longer
>    * supports the format that was originally negotiated. Clients need
>    * to connect a new stream to renegotiate a format and continue
> - * playback, \since 1.0 */
> + * playback. \since 1.0 */
>   #define PA_STREAM_EVENT_FORMAT_LOST "format-lost"
>
>   #ifndef __INCLUDED_FROM_PULSE_AUDIO
>



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