13 files changed, 81 insertions, 43 deletions
diff --git a/src/pulse/channelmap.h b/src/pulse/channelmap.h
index d1d5c8b3..a6b93ddc 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 6ac8ee56..7686456d 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 67aba27d..805d7460 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
 
@@ -57,8 +60,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/introspect.h b/src/pulse/introspect.h
index d4107de0..56dd7079 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
@@ -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 63abd588..19b17fa6 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;
@@ -109,8 +112,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/sample.h b/src/pulse/sample.h
index 7a4a55a0..c9e6fc48 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 31cf7b01..b4fcbd07 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 b1f65374..ecffe4fa 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 */
@@ -140,7 +143,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 b9057885..256b1507 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
 
@@ -486,8 +489,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
@@ -529,9 +532,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 +613,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
@@ -739,8 +743,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 index 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/subscribe.h b/src/pulse/subscribe.h
index 44ed24ae..f1e17ca1 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 2cf496e1..f911228b 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;
@@ -250,7 +253,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 +303,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 */
diff --git a/src/pulse/timeval.h b/src/pulse/timeval.h
index 3cea5d3b..42014638 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 */
diff --git a/src/pulse/volume.h b/src/pulse/volume.h
index 185c3419..594cf91d 100644
--- a/src/pulse/volume.h
+++ b/src/pulse/volume.h
@@ -81,18 +81,21 @@
  *                             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.
  */
 
 /** \file
- * Constants and routines for volume handling */
+ * Constants and routines for volume handling
+ *
+ * See also \subpage volume
+ */
 
 PA_C_DECL_BEGIN
 
@@ -129,13 +132,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 the specified number of channels to the volume v */
 pa_cvolume* pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v);
 
 /** Maximum length of the strings returned by
@@ -259,7 +262,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! */