From 2da3c47838ef548ba13965c145c408f0f01b94c9 Mon Sep 17 00:00:00 2001 From: David Fries Date: Tue, 12 Oct 2010 20:05:47 -0500 Subject: 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 67aba27d..fd173d01 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 63abd588..213f91d8 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 b1f65374..df8758b0 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 46bc02a7..0985f5b2 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 2cf496e1..1c98d543 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 */ -- cgit