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

@@ -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
+    object. No need to free the API as it is owned by the loop
-    it is destroyed when this dies */
+    and is destroyed when the loop is freed. */
 pa_mainloop_api* pa_glib_mainloop_get_api(pa_glib_mainloop *g);
 
 PA_C_DECL_END

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
+    main loop. No need to free the API as it is owned by the loop
-    and it is destroyed when this dies */
+    and is destroyed when the loop is freed. */
 pa_mainloop_api* pa_mainloop_get_api(pa_mainloop*m);
 
 /** Shutdown the main loop */

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

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
+/** Drain a playback stream.  Use this for notification when the
- * is empty. Please note that only one drain operation per stream may
+ * playback buffer is empty after playing all the audio in the buffer.
- * be issued at a time. */
+ * 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
+/** Flush the playback buffer of this stream. This discards any audio
- * better off using the parameter delta of pa_stream_write() instead
+ * in the buffer.  Most of the time you're better off using the parameter
- * of this function. Available on both playback and recording
+ * delta of pa_stream_write() instead of this function. Available on both
- * streams. */
+ * 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

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
+    main loop. No need to free the API as it is owned by the loop
-    and it is destroyed when this dies */
+    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 */