I fixed some doxygen documentation comment typos and grammar. This also adds for exaple 'See also Audio Streams' in stream_8h.html to the overview for Audio Streams to make it easier to get to the overview of those functions.
The patches can also be retrieved by git. git-pull http://spacedout.fries.net/~david/git/pulseaudio dfries_doc -- David Fries <[email protected]> http://fries.net/~david/ (PGP encryption key available)
>From 74454990e4f82308dbbcda1d5876e7a6b724fbc1 Mon Sep 17 00:00:00 2001 From: David Fries <[email protected]> Date: Sat, 18 Sep 2010 09:07:15 -0500 Subject: [PATCH 1/4] doxygen, fix Documentation typos --- src/pulse/introspect.h | 2 +- src/pulse/stream.h | 9 +++++---- src/pulse/timeval.h | 4 ++-- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/src/pulse/introspect.h b/src/pulse/introspect.h index d4107de..539112f 100644 --- a/src/pulse/introspect.h +++ b/src/pulse/introspect.h @@ -59,7 +59,7 @@ * Note that even if a single object is requested, and not the entire list, * the terminating call will still be made. * - * If an error occurs, the callback will be called without and information + * If an error occurs, the callback will be called without an information * structure and eol set to a negative value.. * * Data members in the information structures are only valid during the diff --git a/src/pulse/stream.h b/src/pulse/stream.h index b905788..3a85f86 100644 --- a/src/pulse/stream.h +++ b/src/pulse/stream.h @@ -486,8 +486,8 @@ int pa_stream_cancel_write( * data is not copied. If NULL, the data is copied into an internal * buffer. The client may freely seek around in the output buffer. For * most applications passing 0 and PA_SEEK_RELATIVE as arguments for - * offset and seek should be useful. Afte ther write call succeeded - * the write index will be a the position after where this chunk of + * offset and seek should be useful. After the write call succeeded + * the write index will be at the position after where this chunk of * data has been written to. * * As an optimization for avoiding needless memory copies you may call @@ -739,8 +739,9 @@ pa_operation *pa_stream_proplist_remove(pa_stream *s, const char *const keys[], * 0.9.11 */ int pa_stream_set_monitor_stream(pa_stream *s, uint32_t sink_input_idx); -/** Return what has been set with pa_stream_set_monitor_stream() - * ebfore. \since 0.9.11 */ +/** Return the sink_input_idx previously set with + * pa_stream_set_monitor_stream(). + * \since 0.9.11 */ uint32_t pa_stream_get_monitor_stream(pa_stream *s); PA_C_DECL_END diff --git a/src/pulse/timeval.h b/src/pulse/timeval.h index 3cea5d3..4201463 100644 --- a/src/pulse/timeval.h +++ b/src/pulse/timeval.h @@ -72,10 +72,10 @@ int pa_timeval_cmp(const struct timeval *a, const struct timeval *b) PA_GCC_PURE /** Return the time difference between now and the specified timestamp */ pa_usec_t pa_timeval_age(const struct timeval *tv); -/** Add the specified time inmicroseconds to the specified timeval structure */ +/** Add the specified time in microseconds to the specified timeval structure */ struct timeval* pa_timeval_add(struct timeval *tv, pa_usec_t v); -/** Subtract the specified time inmicroseconds to the specified timeval structure. \since 0.9.11 */ +/** Subtract the specified time in microseconds to the specified timeval structure. \since 0.9.11 */ struct timeval* pa_timeval_sub(struct timeval *tv, pa_usec_t v); /** Store the specified uec value in the timeval struct. \since 0.9.7 */ -- 1.7.1 >From c40f31e154f001cdece146742cf3d93b50c75687 Mon Sep 17 00:00:00 2001 From: David Fries <[email protected]> Date: Tue, 12 Oct 2010 18:22:27 -0500 Subject: [PATCH 2/4] doxygen, volume.h, Fix the "all" comments. Mostly change "Set the volume of all channels" to "Set the volume of the first n channels" as the first is incorrect, it doesn't set all the channels and doesn't explain what n was for. --- src/pulse/volume.h | 21 +++++++++++---------- 1 files changed, 11 insertions(+), 10 deletions(-) diff --git a/src/pulse/volume.h b/src/pulse/volume.h index 185c341..f2c3156 100644 --- a/src/pulse/volume.h +++ b/src/pulse/volume.h @@ -81,12 +81,12 @@ * structure are muted. * \li pa_cvolume_is_norm() - Tests if all channels of a pa_cvolume structure * are at a normal volume. - * \li pa_cvolume_set() - Set all channels of a pa_cvolume structure to a - * certain volume. - * \li pa_cvolume_reset() - Set all channels of a pa_cvolume structure to a - * normal volume. - * \li pa_cvolume_mute() - Set all channels of a pa_cvolume structure to a - * muted volume. + * \li pa_cvolume_set() - Set the first n channels of a pa_cvolume structure to + * a certain volume. + * \li pa_cvolume_reset() - Set the first n channels of a pa_cvolume structure + * to a normal volume. + * \li pa_cvolume_mute() - Set the first n channels of a pa_cvolume structure + * to a muted volume. * \li pa_cvolume_avg() - Return the average volume of all channels. * \li pa_cvolume_snprint() - Pretty print a pa_cvolume structure. */ @@ -129,13 +129,13 @@ int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE; * pa_cvolume_valid() will fail for it. \since 0.9.13 */ pa_cvolume* pa_cvolume_init(pa_cvolume *a); -/** Set the volume of all channels to PA_VOLUME_NORM */ +/** Set the volume of the first n channels to PA_VOLUME_NORM */ #define pa_cvolume_reset(a, n) pa_cvolume_set((a), (n), PA_VOLUME_NORM) -/** Set the volume of all channels to PA_VOLUME_MUTED */ +/** Set the volume of the first n channels to PA_VOLUME_MUTED */ #define pa_cvolume_mute(a, n) pa_cvolume_set((a), (n), PA_VOLUME_MUTED) -/** Set the volume of all channels to the specified parameter */ +/** Set the volume of 0 to channels to the specified parameter */ pa_cvolume* pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v); /** Maximum length of the strings returned by @@ -259,7 +259,8 @@ pa_volume_t pa_sw_volume_from_dB(double f) PA_GCC_CONST; /** Convert a volume to a decibel value (amplitude, not power). This is only valid for software volumes! */ double pa_sw_volume_to_dB(pa_volume_t v) PA_GCC_CONST; -/** Convert a linear factor to a volume. This is only valid for software volumes! */ +/** Convert a linear factor to a volume. 0.0 and less is muted while + * 1.0 is PA_VOLUME_NORM. This is only valid for software volumes! */ pa_volume_t pa_sw_volume_from_linear(double v) PA_GCC_CONST; /** Convert a volume to a linear factor. This is only valid for software volumes! */ -- 1.7.1 >From 1d71ff0312f391951198d3e6d5e9fe95508aac7f Mon Sep 17 00:00:00 2001 From: David Fries <[email protected]> Date: Tue, 12 Oct 2010 20:05:47 -0500 Subject: [PATCH 3/4] doxygen documentation improvements stream.h, simple.h The words drain and flush are a little ambiguous, make it explicit as to what happens to any existing audio. *mainloop.h reword *_free and *_get_api for grammar --- src/pulse/glib-mainloop.h | 4 ++-- src/pulse/mainloop.h | 4 ++-- src/pulse/simple.h | 2 +- src/pulse/stream.h | 15 ++++++++------- src/pulse/thread-mainloop.h | 6 +++--- 5 files changed, 16 insertions(+), 15 deletions(-) diff --git a/src/pulse/glib-mainloop.h b/src/pulse/glib-mainloop.h index 67aba27..fd173d0 100644 --- a/src/pulse/glib-mainloop.h +++ b/src/pulse/glib-mainloop.h @@ -57,8 +57,8 @@ pa_glib_mainloop *pa_glib_mainloop_new(GMainContext *c); void pa_glib_mainloop_free(pa_glib_mainloop* g); /** Return the abstract main loop API vtable for the GLIB main loop - object. No need of freeing the API as it is owned by the loop and - it is destroyed when this dies */ + object. No need to free the API as it is owned by the loop + and is destroyed when the loop is freed. */ pa_mainloop_api* pa_glib_mainloop_get_api(pa_glib_mainloop *g); PA_C_DECL_END diff --git a/src/pulse/mainloop.h b/src/pulse/mainloop.h index 63abd58..213f91d 100644 --- a/src/pulse/mainloop.h +++ b/src/pulse/mainloop.h @@ -109,8 +109,8 @@ int pa_mainloop_iterate(pa_mainloop *m, int block, int *retval); int pa_mainloop_run(pa_mainloop *m, int *retval); /** Return the abstract main loop abstraction layer vtable for this - main loop. No need of freeing the API as it is owned by the loop - and it is destroyed when this dies */ + main loop. No need to free the API as it is owned by the loop + and is destroyed when the loop is freed. */ pa_mainloop_api* pa_mainloop_get_api(pa_mainloop*m); /** Shutdown the main loop */ diff --git a/src/pulse/simple.h b/src/pulse/simple.h index b1f6537..df8758b 100644 --- a/src/pulse/simple.h +++ b/src/pulse/simple.h @@ -140,7 +140,7 @@ int pa_simple_read(pa_simple *s, void*data, size_t bytes, int *error); /** Return the playback latency. */ pa_usec_t pa_simple_get_latency(pa_simple *s, int *error); -/** Flush the playback buffer. */ +/** Flush the playback buffer. This discards any audio in the buffer. */ int pa_simple_flush(pa_simple *s, int *error); PA_C_DECL_END diff --git a/src/pulse/stream.h b/src/pulse/stream.h index 3a85f86..158776b 100644 --- a/src/pulse/stream.h +++ b/src/pulse/stream.h @@ -529,9 +529,10 @@ size_t pa_stream_writable_size(pa_stream *p); /** Return the number of bytes that may be read using pa_stream_peek()*/ size_t pa_stream_readable_size(pa_stream *p); -/** Drain a playback stream. Use this for notification when the buffer - * is empty. Please note that only one drain operation per stream may - * be issued at a time. */ +/** Drain a playback stream. Use this for notification when the + * playback buffer is empty after playing all the audio in the buffer. + * Please note that only one drain operation per stream may be issued + * at a time. */ pa_operation* pa_stream_drain(pa_stream *s, pa_stream_success_cb_t cb, void *userdata); /** Request a timing info structure update for a stream. Use @@ -609,10 +610,10 @@ void pa_stream_set_buffer_attr_callback(pa_stream *p, pa_stream_notify_cb_t cb, * of the stream it will be created in corked state. */ pa_operation* pa_stream_cork(pa_stream *s, int b, pa_stream_success_cb_t cb, void *userdata); -/** Flush the playback buffer of this stream. Most of the time you're - * better off using the parameter delta of pa_stream_write() instead - * of this function. Available on both playback and recording - * streams. */ +/** Flush the playback buffer of this stream. This discards any audio + * in the buffer. Most of the time you're better off using the parameter + * delta of pa_stream_write() instead of this function. Available on both + * playback and recording streams. */ pa_operation* pa_stream_flush(pa_stream *s, pa_stream_success_cb_t cb, void *userdata); /** Reenable prebuffering as specified in the pa_buffer_attr diff --git a/src/pulse/thread-mainloop.h b/src/pulse/thread-mainloop.h index 2cf496e..1c98d54 100644 --- a/src/pulse/thread-mainloop.h +++ b/src/pulse/thread-mainloop.h @@ -250,7 +250,7 @@ typedef struct pa_threaded_mainloop pa_threaded_mainloop; pa_threaded_mainloop *pa_threaded_mainloop_new(void); /** Free a threaded main loop object. If the event loop thread is - * still running, it is terminated using pa_threaded_mainloop_stop() + * still running, terminate it with pa_threaded_mainloop_stop() * first. */ void pa_threaded_mainloop_free(pa_threaded_mainloop* m); @@ -300,8 +300,8 @@ void pa_threaded_mainloop_accept(pa_threaded_mainloop *m); int pa_threaded_mainloop_get_retval(pa_threaded_mainloop *m); /** Return the abstract main loop abstraction layer vtable for this - main loop. No need of freeing the API as it is owned by the loop - and it is destroyed when this dies */ + main loop. No need to free the API as it is owned by the loop + and is destroyed when the loop is freed. */ pa_mainloop_api* pa_threaded_mainloop_get_api(pa_threaded_mainloop*m); /** Returns non-zero when called from withing the event loop thread. \since 0.9.7 */ -- 1.7.1 >From 720dde60e6d17d20cc920774d941d125dc556913 Mon Sep 17 00:00:00 2001 From: David Fries <[email protected]> Date: Sun, 3 Oct 2010 13:41:27 -0500 Subject: [PATCH 4/4] doxygen, add 'See also' linking to the overview page A good many of the header files are broken into a function reference page and an overview page. These changes add a direct link from each function reference page to their overview page if one exists. --- src/pulse/channelmap.h | 5 ++++- src/pulse/context.h | 5 ++++- src/pulse/glib-mainloop.h | 5 ++++- src/pulse/introspect.h | 2 ++ src/pulse/mainloop.h | 5 ++++- src/pulse/sample.h | 5 ++++- src/pulse/scache.h | 5 ++++- src/pulse/simple.h | 5 ++++- src/pulse/stream.h | 5 ++++- src/pulse/subscribe.h | 5 ++++- src/pulse/thread-mainloop.h | 5 ++++- src/pulse/volume.h | 5 ++++- 12 files changed, 46 insertions(+), 11 deletions(-) diff --git a/src/pulse/channelmap.h b/src/pulse/channelmap.h index d1d5c8b..a6b93dd 100644 --- a/src/pulse/channelmap.h +++ b/src/pulse/channelmap.h @@ -65,7 +65,10 @@ */ /** \file - * Constants and routines for channel mapping handling */ + * Constants and routines for channel mapping handling + * + * See also \subpage channelmap + */ PA_C_DECL_BEGIN diff --git a/src/pulse/context.h b/src/pulse/context.h index 6ac8ee5..7686456 100644 --- a/src/pulse/context.h +++ b/src/pulse/context.h @@ -145,7 +145,10 @@ /** \file * Connection contexts for asynchrononous communication with a * server. A pa_context object wraps a connection to a PulseAudio - * server using its native protocol. */ + * server using its native protocol. + * + * See also \subpage async + */ PA_C_DECL_BEGIN diff --git a/src/pulse/glib-mainloop.h b/src/pulse/glib-mainloop.h index fd173d0..805d746 100644 --- a/src/pulse/glib-mainloop.h +++ b/src/pulse/glib-mainloop.h @@ -41,7 +41,10 @@ */ /** \file - * GLIB main loop support */ + * GLIB main loop support + * + * See also \subpage glib-mainloop + */ PA_C_DECL_BEGIN diff --git a/src/pulse/introspect.h b/src/pulse/introspect.h index 539112f..56dd707 100644 --- a/src/pulse/introspect.h +++ b/src/pulse/introspect.h @@ -187,6 +187,8 @@ /** \file * * Routines for daemon introspection. + * + * See also \subpage introspect */ PA_C_DECL_BEGIN diff --git a/src/pulse/mainloop.h b/src/pulse/mainloop.h index 213f91d..19b17fa 100644 --- a/src/pulse/mainloop.h +++ b/src/pulse/mainloop.h @@ -71,7 +71,10 @@ struct pollfd; * function. Using the routines defined herein you may create a simple * main loop supporting the generic main loop abstraction layer as * defined in \ref mainloop-api.h. This implementation is thread safe - * as long as you access the main loop object from a single thread only.*/ + * as long as you access the main loop object from a single thread only. + * + * See also \subpage mainloop + */ /** An opaque main loop object */ typedef struct pa_mainloop pa_mainloop; diff --git a/src/pulse/sample.h b/src/pulse/sample.h index 7a4a55a..c9e6fc4 100644 --- a/src/pulse/sample.h +++ b/src/pulse/sample.h @@ -105,7 +105,10 @@ */ /** \file - * Constants and routines for sample type handling */ + * Constants and routines for sample type handling + * + * See also \subpage sample + */ PA_C_DECL_BEGIN diff --git a/src/pulse/scache.h b/src/pulse/scache.h index 31cf7b0..b4fcbd0 100644 --- a/src/pulse/scache.h +++ b/src/pulse/scache.h @@ -74,7 +74,10 @@ */ /** \file - * All sample cache related routines */ + * All sample cache related routines + * + * See also \subpage scache + */ PA_C_DECL_BEGIN diff --git a/src/pulse/simple.h b/src/pulse/simple.h index df8758b..ecffe4f 100644 --- a/src/pulse/simple.h +++ b/src/pulse/simple.h @@ -98,7 +98,10 @@ /** \file * A simple but limited synchronous playback and recording * API. This is a synchronous, simplified wrapper around the standard - * asynchronous API. */ + * asynchronous API. + * + * See also \subpage simple + */ /** \example pacat-simple.c * A simple playback tool using the simple API */ diff --git a/src/pulse/stream.h b/src/pulse/stream.h index 158776b..559e188 100644 --- a/src/pulse/stream.h +++ b/src/pulse/stream.h @@ -310,7 +310,10 @@ */ /** \file - * Audio streams for input, output and sample upload */ + * Audio streams for input, output and sample upload + * + * See also \subpage streams + */ PA_C_DECL_BEGIN diff --git a/src/pulse/subscribe.h b/src/pulse/subscribe.h index 44ed24a..f1e17ca 100644 --- a/src/pulse/subscribe.h +++ b/src/pulse/subscribe.h @@ -45,7 +45,10 @@ */ /** \file - * Daemon introspection event subscription subsystem. */ + * Daemon introspection event subscription subsystem. + * + * See also \subpage subscribe + */ PA_C_DECL_BEGIN diff --git a/src/pulse/thread-mainloop.h b/src/pulse/thread-mainloop.h index 1c98d54..f911228 100644 --- a/src/pulse/thread-mainloop.h +++ b/src/pulse/thread-mainloop.h @@ -239,7 +239,10 @@ PA_C_DECL_BEGIN * A thread based event loop implementation based on pa_mainloop. The * event loop is run in a helper thread in the background. A few * synchronization primitives are available to access the objects - * attached to the event loop safely. */ + * attached to the event loop safely. + * + * See also \subpage threaded_mainloop + */ /** An opaque threaded main loop object */ typedef struct pa_threaded_mainloop pa_threaded_mainloop; diff --git a/src/pulse/volume.h b/src/pulse/volume.h index f2c3156..cd3f05e 100644 --- a/src/pulse/volume.h +++ b/src/pulse/volume.h @@ -92,7 +92,10 @@ */ /** \file - * Constants and routines for volume handling */ + * Constants and routines for volume handling + * + * See also \subpage volume + */ PA_C_DECL_BEGIN -- 1.7.1
_______________________________________________ pulseaudio-discuss mailing list [email protected] https://tango.0pointer.de/mailman/listinfo/pulseaudio-discuss
