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/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 */