api documentation improvements

includes typo fixes, neatening, addition of more return info, and such.

15 files changed, 205 insertions, 143 deletions

diff --git a/src/pulse/channelmap.h b/src/pulse/channelmap.h
index 6eabe20ba..290e1ed2e 100644
--- a/src/pulse/channelmap.h
+++ b/src/pulse/channelmap.h
@@ -46,10 +46,12 @@
  *
  * \li pa_channel_map_init_mono() - Create a channel map with only mono audio.
  * \li pa_channel_map_init_stereo() - Create a standard stereo mapping.
- * \li pa_channel_map_init_auto() - Create a standard channel map for a specific number of channels
- * \li pa_channel_map_init_extend() - Similar to
- * pa_channel_map_init_auto() but synthesize a channel map if no
- * predefined one is known for the specified number of channels.
+ * \li pa_channel_map_init_auto() - Create a standard channel map for a specific
+ *                                  number of channels.
+ * \li pa_channel_map_init_extend() - Similar to pa_channel_map_init_auto() but
+ *                                    synthesize a channel map if no predefined
+ *                                    one is known for the specified number of
+ *                                    channels.
  *
  * \section conv_sec Convenience Functions
  *
@@ -261,7 +263,7 @@ typedef enum pa_channel_map_def {
  * mixing of streams */
 typedef struct pa_channel_map {
     uint8_t channels;
-    /**< Number of channels */
+    /**< Number of channels mapped */
 
     pa_channel_position_t map[PA_CHANNELS_MAX];
     /**< Channel labels */
@@ -306,7 +308,7 @@ const char* pa_channel_position_to_pretty_string(pa_channel_position_t pos);
  * it might become part of an ABI. */
 #define PA_CHANNEL_MAP_SNPRINT_MAX 336
 
-/** Make a human readable string from the specified channel map */
+/** Make a human readable string from the specified channel map. Returns \a s. */
 char* pa_channel_map_snprint(char *s, size_t l, const pa_channel_map *map);
 
 /** Parse a channel position list or well-known mapping name into a
diff --git a/src/pulse/context.h b/src/pulse/context.h
index ae2a06825..9b96f8ce5 100644
--- a/src/pulse/context.h
+++ b/src/pulse/context.h
@@ -46,7 +46,7 @@
  *                       that some implementations may block all other events
  *                       when a deferred event is active.
  * \li I/O events - Events that trigger on file descriptor activities.
- * \li Times events - Events that trigger after a fixed amount of time.
+ * \li Timer events - Events that trigger after a fixed amount of time.
  *
  * The abstraction is represented as a number of function pointers in the
  * pa_mainloop_api structure.
@@ -199,13 +199,14 @@ int pa_context_is_pending(pa_context *c);
 pa_context_state_t pa_context_get_state(pa_context *c);
 
 /** Connect the context to the specified server. If server is NULL,
-connect to the default server. This routine may but will not always
-return synchronously on error. Use pa_context_set_state_callback() to
-be notified when the connection is established. If flags doesn't have
-PA_CONTEXT_NOAUTOSPAWN set and no specific server is specified or
-accessible a new daemon is spawned. If api is non-NULL, the functions
-specified in the structure are used when forking a new child
-process. */
+ * connect to the default server. This routine may but will not always
+ * return synchronously on error. Use pa_context_set_state_callback() to
+ * be notified when the connection is established. If flags doesn't have
+ * PA_CONTEXT_NOAUTOSPAWN set and no specific server is specified or
+ * accessible a new daemon is spawned. If api is non-NULL, the functions
+ * specified in the structure are used when forking a new child
+ * process. Returns negative on certain errors such as invalid state
+ * or parameters. */
 int pa_context_connect(pa_context *c, const char *server, pa_context_flags_t flags, const pa_spawn_api *api);
 
 /** Terminate the context connection immediately */
@@ -237,11 +238,12 @@ const char* pa_context_get_server(pa_context *c);
 /** Return the protocol version of the library. */
 uint32_t pa_context_get_protocol_version(pa_context *c);
 
-/** Return the protocol version of the connected server. */
+/** Return the protocol version of the connected server.
+ * Returns PA_INVALID_INDEX on error. */
 uint32_t pa_context_get_server_protocol_version(pa_context *c);
 
 /** Update the property list of the client, adding new entries. Please
- * note that it is highly recommended to set as much properties
+ * note that it is highly recommended to set as many properties
  * initially via pa_context_new_with_proplist() as possible instead a
  * posteriori with this function, since that information may then be
  * used to route streams of the client to the right device. \since 0.9.11 */
@@ -252,7 +254,8 @@ pa_operation *pa_context_proplist_remove(pa_context *c, const char *const keys[]
 
 /** Return the client index this context is
  * identified in the server with. This is useful for usage with the
- * introspection functions, such as pa_context_get_client_info(). \since 0.9.11 */
+ * introspection functions, such as pa_context_get_client_info().
+ * Returns PA_INVALID_INDEX on error. \since 0.9.11 */
 uint32_t pa_context_get_index(pa_context *s);
 
 /** Create a new timer event source for the specified time (wrapper
@@ -271,7 +274,8 @@ void pa_context_rttime_restart(pa_context *c, pa_time_event *e, pa_usec_t usec);
  * of this size. It is not recommended writing smaller blocks than
  * this (unless required due to latency demands) because this
  * increases CPU usage. If ss is NULL you will be returned the
- * byte-exact tile size. If you pass a valid ss, then the tile size
+ * byte-exact tile size. if ss is invalid, (size_t) -1 will be
+ * returned. If you pass a valid ss, then the tile size
  * will be rounded down to multiple of the frame size. This is
  * supposed to be used in a construct such as
  * pa_context_get_tile_size(pa_stream_get_context(s),
diff --git a/src/pulse/def.h b/src/pulse/def.h
index 87b7dd40a..7211b60ec 100644
--- a/src/pulse/def.h
+++ b/src/pulse/def.h
@@ -97,7 +97,7 @@ typedef enum pa_operation_state {
     /**< The operation has completed */
     PA_OPERATION_CANCELLED
     /**< The operation has been cancelled. Operations may get cancelled by the
-     * application, or as a result of the context getting disconneted while the
+     * application, or as a result of the context getting disconnected while the
      * operation is pending. */
 } pa_operation_state_t;
 
@@ -118,7 +118,9 @@ typedef enum pa_context_flags {
     PA_CONTEXT_NOAUTOSPAWN = 0x0001U,
     /**< Disabled autospawning of the PulseAudio daemon if required */
     PA_CONTEXT_NOFAIL = 0x0002U
-    /**< Don't fail if the daemon is not available when pa_context_connect() is called, instead enter PA_CONTEXT_CONNECTING state and wait for the daemon to appear.  \since 0.9.15 */
+    /**< Don't fail if the daemon is not available when pa_context_connect() is
+     * called, instead enter PA_CONTEXT_CONNECTING state and wait for the daemon
+     * to appear.  \since 0.9.15 */
 } pa_context_flags_t;
 
 /** \cond fulldocs */
@@ -259,7 +261,7 @@ typedef enum pa_stream_flags {
     PA_STREAM_FIX_CHANNELS = 0x0100,
     /**< Use the number of channels and the channel map of the sink,
      * and possibly ignore the number of channels and the map the
-     * sample spec and the passed channel map contains. Usage similar
+     * sample spec and the passed channel map contain. Usage similar
      * to PA_STREAM_FIX_FORMAT. Only supported when the server is at
      * least PA 0.9.8. It is ignored on older servers.
      *
@@ -295,7 +297,7 @@ typedef enum pa_stream_flags {
 
     PA_STREAM_START_MUTED = 0x1000U,
     /**< Create in muted state. If neither PA_STREAM_START_UNMUTED nor
-     * PA_STREAM_START_MUTED it is left to the server to decide
+     * PA_STREAM_START_MUTED are set, it is left to the server to decide
      * whether to create the stream in muted or in unmuted
      * state. \since 0.9.11 */
 
@@ -330,7 +332,7 @@ typedef enum pa_stream_flags {
 
     PA_STREAM_START_UNMUTED = 0x10000U,
     /**< Create in unmuted state. If neither PA_STREAM_START_UNMUTED
-     * nor PA_STREAM_START_MUTED it is left to the server to decide
+     * nor PA_STREAM_START_MUTED are set it is left to the server to decide
      * whether to create the stream in muted or in unmuted
      * state. \since 0.9.15 */
 
@@ -703,7 +705,7 @@ typedef struct pa_timing_info {
     int64_t write_index;
     /**< Current write index into the playback buffer in bytes. Think
      * twice before using this for seeking purposes: it might be out
-     * of date a the time you want to use it. Consider using
+     * of date at the time you want to use it. Consider using
      * PA_SEEK_RELATIVE instead. */
 
     int read_index_corrupt;
@@ -714,7 +716,7 @@ typedef struct pa_timing_info {
     int64_t read_index;
     /**< Current read index into the playback buffer in bytes. Think
      * twice before using this for seeking purposes: it might be out
-     * of date a the time you want to use it. Consider using
+     * of date at the time you want to use it. Consider using
      * PA_SEEK_RELATIVE_ON_READ instead. */
 
     pa_usec_t configured_sink_usec;
@@ -758,16 +760,16 @@ typedef struct pa_spawn_api {
 /** Seek type for pa_stream_write(). */
 typedef enum pa_seek_mode {
     PA_SEEK_RELATIVE = 0,
-    /**< Seek relatively to the write index */
+    /**< Seek relative to the write index. */
 
     PA_SEEK_ABSOLUTE = 1,
-    /**< Seek relatively to the start of the buffer queue */
+    /**< Seek relative to the start of the buffer queue. */
 
     PA_SEEK_RELATIVE_ON_READ = 2,
-    /**< Seek relatively to the read index.  */
+    /**< Seek relative to the read index. */
 
     PA_SEEK_RELATIVE_END = 3
-    /**< Seek relatively to the current end of the buffer queue. */
+    /**< Seek relative to the current end of the buffer queue. */
 } pa_seek_mode_t;
 
 /** \cond fulldocs */
diff --git a/src/pulse/format.h b/src/pulse/format.h
index f606b3b5f..2143bb514 100644
--- a/src/pulse/format.h
+++ b/src/pulse/format.h
@@ -78,7 +78,8 @@ typedef enum pa_encoding {
 /** Returns a printable string representing the given encoding type. \since 1.0 */
 const char *pa_encoding_to_string(pa_encoding_t e) PA_GCC_CONST;
 
-/** Converts a string of the form returned by \a pa_encoding_to_string() back to a \a pa_encoding_t. \since 1.0 */
+/** Converts a string of the form returned by \a pa_encoding_to_string() back to
+ * a \a pa_encoding_t. \since 1.0 */
 pa_encoding_t pa_encoding_from_string(const char *encoding);
 
 /** Represents the format of data provided in a stream or processed by a sink. \since 1.0 */
@@ -90,7 +91,8 @@ typedef struct pa_format_info {
     /**< Additional encoding-specific properties such as sample rate, bitrate, etc. */
 } pa_format_info;
 
-/** Allocates a new \a pa_format_info structure. Clients must initialise at least the encoding field themselves. \since 1.0 */
+/** Allocates a new \a pa_format_info structure. Clients must initialise at
+ * least the encoding field themselves. Free with pa_format_info_free. \since 1.0 */
 pa_format_info* pa_format_info_new(void);
 
 /** Returns a new \a pa_format_info struct and representing the same format as \a src. \since 1.0 */
@@ -102,7 +104,8 @@ void pa_format_info_free(pa_format_info *f);
 /** Returns non-zero when the format info structure is valid. \since 1.0 */
 int pa_format_info_valid(const pa_format_info *f);
 
-/** Returns non-zero when the format info structure represents a PCM (i.e.\ uncompressed data) format. \since 1.0 */
+/** Returns non-zero when the format info structure represents a PCM
+ * (i.e.\ uncompressed data) format. \since 1.0 */
 int pa_format_info_is_pcm(const pa_format_info *f);
 
 /** Returns non-zero if the format represented by \a first is a subset of
@@ -121,7 +124,7 @@ int pa_format_info_is_compatible(const pa_format_info *first, const pa_format_in
  * it might become part of an ABI. \since 1.0 */
 #define PA_FORMAT_INFO_SNPRINT_MAX 256
 
-/** Return a human-readable string representing the given format. \since 1.0 */
+/** Make a human-readable string representing the given format. Returns \a s. \since 1.0 */
 char *pa_format_info_snprint(char *s, size_t l, const pa_format_info *f);
 
 /** Parse a human-readable string of the form generated by
diff --git a/src/pulse/mainloop-api.h b/src/pulse/mainloop-api.h
index 4d847313a..f04ba2099 100644
--- a/src/pulse/mainloop-api.h
+++ b/src/pulse/mainloop-api.h
@@ -31,14 +31,21 @@
  * Main loop abstraction layer. Both the PulseAudio core and the
  * PulseAudio client library use a main loop abstraction layer. Due to
  * this it is possible to embed PulseAudio into other
- * applications easily. Two main loop implementations are
+ * applications easily. Three main loop implementations are
  * currently available:
- * \li A minimal implementation based on the C library's poll() function (See \ref mainloop.h)
- * \li A wrapper around the GLIB main loop. Use this to embed PulseAudio into your GLIB/GTK+/GNOME programs (See \ref glib-mainloop.h)
+ * \li A minimal implementation based on the C library's poll() function
+ *     (See \ref mainloop.h).
+ * \li A special version of the previous implementation where all of
+ *     PulseAudio's internal handling runs in a separate thread
+ *     (See \ref thread-mainloop.h).
+ * \li A wrapper around the GLIB main loop. Use this to embed PulseAudio into
+ *     your GLIB/GTK+/GNOME programs (See \ref glib-mainloop.h).
  *
- * The structure pa_mainloop_api is used as vtable for the main loop abstraction.
+ * The structure pa_mainloop_api is used as a vtable for the main loop abstraction.
  *
- * This mainloop abstraction layer has no direct support for UNIX signals. Generic, mainloop implementation agnostic support is available through \ref mainloop-signal.h.
+ * This mainloop abstraction layer has no direct support for UNIX signals.
+ * Generic, mainloop implementation agnostic support is available through
+ * \ref mainloop-signal.h.
  * */
 
 PA_C_DECL_BEGIN
diff --git a/src/pulse/mainloop.h b/src/pulse/mainloop.h
index 6e2ca5f9b..a7df8a19e 100644
--- a/src/pulse/mainloop.h
+++ b/src/pulse/mainloop.h
@@ -77,7 +77,7 @@ struct pollfd;
 /** An opaque main loop object */
 typedef struct pa_mainloop pa_mainloop;
 
-/** Allocate a new main loop object */
+/** Allocate a new main loop object. Free with pa_mainloop_free. */
 pa_mainloop *pa_mainloop_new(void);
 
 /** Free a main loop object */
@@ -106,7 +106,10 @@ specified with the main loop's quit() routine in the integer variable retval poi
 to. On success returns the number of sources dispatched in this iteration. */
 int pa_mainloop_iterate(pa_mainloop *m, int block, int *retval);
 
-/** Run unlimited iterations of the main loop object until the main loop's quit() routine is called. */
+/** Run unlimited iterations of the main loop object until the main loop's
+quit() routine is called. Returns a negative value on error. Optionally return
+the return value as specified with the main loop's quit() routine in the integer
+variable retval points to. */
 int pa_mainloop_run(pa_mainloop *m, int *retval);
 
 /** Return the abstract main loop abstraction layer vtable for this
diff --git a/src/pulse/proplist.h b/src/pulse/proplist.h
index bc9e8f8ef..cec3b3574 100644
--- a/src/pulse/proplist.h
+++ b/src/pulse/proplist.h
@@ -271,7 +271,7 @@ PA_C_DECL_BEGIN
  * as keys and arbitrary data as values. \since 0.9.11 */
 typedef struct pa_proplist pa_proplist;
 
-/** Allocate a property list. \since 0.9.11 */
+/** Allocate a property list. Free with pa_proplist_free. \since 0.9.11 */
 pa_proplist* pa_proplist_new(void);
 
 /** Free the property list. \since 0.9.11 */
@@ -283,7 +283,7 @@ int pa_proplist_key_valid(const char *key);
 /** Append a new string entry to the property list, possibly
  * overwriting an already existing entry with the same key. An
  * internal copy of the data passed is made. Will accept only valid
- * UTF-8. \since 0.9.11 */
+ * UTF-8. Returns zero on success. \since 0.9.11 */
 int pa_proplist_sets(pa_proplist *p, const char *key, const char *value);
 
 /** Append a new string entry to the property list, possibly
@@ -291,19 +291,20 @@ int pa_proplist_sets(pa_proplist *p, const char *key, const char *value);
  * internal copy of the data passed is made. Will accept only valid
  * UTF-8. The string passed in must contain a '='. Left hand side of
  * the '=' is used as key name, the right hand side as string
- * data. \since 0.9.16 */
+ * data. Returns zero on success. \since 0.9.16 */
 int pa_proplist_setp(pa_proplist *p, const char *pair);
 
 /** Append a new string entry to the property list, possibly
  * overwriting an already existing entry with the same key. An
  * internal copy of the data passed is made. Will accept only valid
  * UTF-8. The data can be passed as printf()-style format string with
- * arguments. \since 0.9.11 */
+ * arguments. Returns zero on success. \since 0.9.11 */
 int pa_proplist_setf(pa_proplist *p, const char *key, const char *format, ...) PA_GCC_PRINTF_ATTR(3,4);
 
 /** Append a new arbitrary data entry to the property list, possibly
  * overwriting an already existing entry with the same key. An
- * internal copy of the data passed is made. \since 0.9.11 */
+ * internal copy of the data passed is made.
+ * Returns zero on success. \since 0.9.11 */
 int pa_proplist_set(pa_proplist *p, const char *key, const void *data, size_t nbytes);
 
 /** Return a string entry for the specified key. Will return NULL if
@@ -315,8 +316,8 @@ const char *pa_proplist_gets(pa_proplist *p, const char *key);
 /** Store the value for the specified key in \a data. Will store a
  * NUL-terminated string for string entries. The \a data pointer returned will
  * point to an internally allocated buffer. The caller should make a
- * copy of the data before the property list is accessed again. \since
- * 0.9.11 */
+ * copy of the data before the property list is accessed again.
+ * Returns zero on success, negative on error. \since 0.9.11 */
 int pa_proplist_get(pa_proplist *p, const char *key, const void **data, size_t *nbytes);
 
 /** Update mode enum for pa_proplist_update(). \since 0.9.11 */
@@ -347,7 +348,8 @@ typedef enum pa_update_mode {
 void pa_proplist_update(pa_proplist *p, pa_update_mode_t mode, const pa_proplist *other);
 
 /** Removes a single entry from the property list, identified be the
- * specified key name. \since 0.9.11 */
+ * specified key name. Returns zero on success, negative on error.
+ * \since 0.9.11 */
 int pa_proplist_unset(pa_proplist *p, const char *key);
 
 /** Similar to pa_proplist_unset() but takes an array of keys to
@@ -384,7 +386,7 @@ char *pa_proplist_to_string_sep(pa_proplist *p, const char *sep);
 pa_proplist *pa_proplist_from_string(const char *str);
 
 /** Returns 1 if an entry for the specified key exists in the
- * property list. \since 0.9.11 */
+ * property list. Returns negative on error. \since 0.9.11 */
 int pa_proplist_contains(pa_proplist *p, const char *key);
 
 /** Remove all entries from the property list object. \since 0.9.11 */
diff --git a/src/pulse/pulseaudio.h b/src/pulse/pulseaudio.h
index 063d5e230..e9fec55d9 100644
--- a/src/pulse/pulseaudio.h
+++ b/src/pulse/pulseaudio.h
@@ -114,11 +114,11 @@
  * integer value or a NULL pointer. On success, zero or a positive integer
  * value or a valid pointer is returned.
  *
- * Functions of the \ref simple generally return -1 or NULL on failure and
+ * Functions of the \ref simple API generally return -1 or NULL on failure and
  * can optionally store an error code (see ::pa_error_code) using a pointer
  * argument.
  *
- * Functions of the \ref async return an negative error code or NULL on
+ * Functions of the \ref async API return an negative error code or NULL on
  * failure (see ::pa_error_code). In the later case, pa_context_errno()
  * can be used to obtain the error code of the last failed operation.
  *
diff --git a/src/pulse/sample.h b/src/pulse/sample.h
index 4299eecff..b368fdace 100644
--- a/src/pulse/sample.h
+++ b/src/pulse/sample.h
@@ -259,7 +259,8 @@ typedef struct pa_sample_spec {
 /** Type for usec specifications (unsigned). Always 64 bit. */
 typedef uint64_t pa_usec_t;
 
-/** Return the amount of bytes playback of a second of audio with the specified sample type takes */
+/** Return the amount of bytes that constitute playback of one second of
+ * audio, with the specified sample spec. */
 size_t pa_bytes_per_second(const pa_sample_spec *spec) PA_GCC_PURE;
 
 /** Return the size of a frame with the specific sample type */
@@ -272,13 +273,14 @@ size_t pa_sample_size(const pa_sample_spec *spec) PA_GCC_PURE;
  * full sample spec. \since 0.9.15 */
 size_t pa_sample_size_of_format(pa_sample_format_t f) PA_GCC_PURE;
 
-/** Calculate the time the specified bytes take to play with the
- * specified sample type. The return value will always be rounded
- * down for non-integral return values. */
+/** Calculate the time it would take to play a buffer of the specified
+ * size with the specified sample type. The return value will always
+ * be rounded down for non-integral return values. */
 pa_usec_t pa_bytes_to_usec(uint64_t length, const pa_sample_spec *spec) PA_GCC_PURE;
 
-/** Calculates the number of bytes that are required for the specified
- * time. The return value will always be rounded down for non-integral
+/** Calculates the size of a buffer required, for playback duration
+ * of the time specified, with the specified sample type. The
+ * return value will always be rounded down for non-integral
  * return values. \since 0.9 */
 size_t pa_usec_to_bytes(pa_usec_t t, const pa_sample_spec *spec) PA_GCC_PURE;
 
@@ -316,7 +318,7 @@ pa_sample_format_t pa_parse_sample_format(const char *format) PA_GCC_PURE;
  * it might become part of an ABI. */
 #define PA_SAMPLE_SPEC_SNPRINT_MAX 32
 
-/** Pretty print a sample type specification to a string */
+/** Pretty print a sample type specification to a string. Returns \a s. */
 char* pa_sample_spec_snprint(char *s, size_t l, const pa_sample_spec *spec);
 
 /** Maximum required string length for pa_bytes_snprint(). Please note
@@ -326,26 +328,30 @@ char* pa_sample_spec_snprint(char *s, size_t l, const pa_sample_spec *spec);
  * ABI. \since 0.9.16 */
 #define PA_BYTES_SNPRINT_MAX 11
 
-/** Pretty print a byte size value (i.e.\ "2.5 MiB") */
+/** Pretty print a byte size value (i.e.\ "2.5 MiB"). Returns \a s. */
 char* pa_bytes_snprint(char *s, size_t l, unsigned v);
 
-/** Return 1 when the specified format is little endian, return -1
- * when endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is little endian, 0 when
+ * big endian. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
 int pa_sample_format_is_le(pa_sample_format_t f) PA_GCC_PURE;
 
-/** Return 1 when the specified format is big endian, return -1 when
- * endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is big endian, 0 when
+ * little endian. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
 int pa_sample_format_is_be(pa_sample_format_t f) PA_GCC_PURE;
 
 #ifdef WORDS_BIGENDIAN
 #define pa_sample_format_is_ne(f) pa_sample_format_is_be(f)
 #define pa_sample_format_is_re(f) pa_sample_format_is_le(f)
 #else
-/** Return 1 when the specified format is native endian, return -1
- * when endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is native endian, 0 when
+ * not. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
 #define pa_sample_format_is_ne(f) pa_sample_format_is_le(f)
-/** Return 1 when the specified format is reverse endian, return -1
- * when endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is reverse endian, 0 when
+ * native. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
 #define pa_sample_format_is_re(f) pa_sample_format_is_be(f)
 #endif
 
diff --git a/src/pulse/scache.h b/src/pulse/scache.h
index e799b1d14..2b85854e2 100644
--- a/src/pulse/scache.h
+++ b/src/pulse/scache.h
@@ -84,15 +84,16 @@ PA_C_DECL_BEGIN
  * PA_INVALID_INDEX on failure. \since 0.9.11 */
 typedef void (*pa_context_play_sample_cb_t)(pa_context *c, uint32_t idx, void *userdata);
 
-/** Make this stream a sample upload stream */
+/** Make this stream a sample upload stream. Returns zero on success. */
 int pa_stream_connect_upload(pa_stream *s, size_t length);
 
 /** Finish the sample upload, the stream name will become the sample
  * name. You cancel a sample upload by issuing
- * pa_stream_disconnect() */
+ * pa_stream_disconnect(). Returns zero on success. */
 int pa_stream_finish_upload(pa_stream *s);
 
-/** Remove a sample from the sample cache. Returns an operation object which may be used to cancel the operation while it is running */
+/** Remove a sample from the sample cache. Returns an operation object which
+ * may be used to cancel the operation while it is running. */
 pa_operation* pa_context_remove_sample(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
 
 /** Play a sample from the sample cache to the specified device. If
@@ -102,7 +103,7 @@ pa_operation* pa_context_play_sample(
         pa_context *c               /**< Context */,
         const char *name            /**< Name of the sample to play */,
         const char *dev             /**< Sink to play this sample on */,
-        pa_volume_t volume          /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side which is a good idea. */ ,
+        pa_volume_t volume          /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side, which is a good idea. */ ,
         pa_context_success_cb_t cb  /**< Call this function after successfully starting playback, or NULL */,
         void *userdata              /**< Userdata to pass to the callback */);
 
@@ -114,7 +115,7 @@ pa_operation* pa_context_play_sample_with_proplist(
         pa_context *c                   /**< Context */,
         const char *name                /**< Name of the sample to play */,
         const char *dev                 /**< Sink to play this sample on */,
-        pa_volume_t volume              /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side which is a good idea.  */ ,
+        pa_volume_t volume              /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side, which is a good idea.  */ ,
         pa_proplist *proplist           /**< Property list for this sound. The property list of the cached entry will be merged into this property list */,
         pa_context_play_sample_cb_t cb  /**< Call this function after successfully starting playback, or NULL */,
         void *userdata                  /**< Userdata to pass to the callback */);
diff --git a/src/pulse/simple.h b/src/pulse/simple.h
index 7b84f71b5..44ae65d85 100644
--- a/src/pulse/simple.h
+++ b/src/pulse/simple.h
@@ -130,15 +130,16 @@ pa_simple* pa_simple_new(
 /** Close and free the connection to the server. The connection object becomes invalid when this is called. */
 void pa_simple_free(pa_simple *s);
 
-/** Write some data to the server. */
+/** Write some data to the server. Returns zero on success, negative on error. */
 int pa_simple_write(pa_simple *s, const void *data, size_t bytes, int *error);
 
-/** Wait until all data already written is played by the daemon. */
+/** Wait until all data already written is played by the daemon.
+ * Returns zero on success, negative on error. */
 int pa_simple_drain(pa_simple *s, int *error);
 
 /** Read some data from the server. This function blocks until \a bytes amount
  * of data has been received from the server, or until an error occurs.
- * Returns a negative value on failure. */
+ * Returns zero on success, negative on failure. */
 int pa_simple_read(
     pa_simple *s, /**< The connection object. */
     void *data,   /**< A pointer to a buffer. */
@@ -151,7 +152,8 @@ int pa_simple_read(
 /** Return the playback or record latency. */
 pa_usec_t pa_simple_get_latency(pa_simple *s, int *error);
 
-/** Flush the playback or record buffer. This discards any audio in the buffer. */
+/** Flush the playback or record buffer. This discards any audio in the buffer.
+ * Returns zero on success, negative on error. */
 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 7b9ba98b9..686279841 100644
--- a/src/pulse/stream.h
+++ b/src/pulse/stream.h
@@ -186,7 +186,7 @@
  * Once the stream is up, data can start flowing between the client and the
  * server. Two different access models can be used to transfer the data:
  *
- * \li Asynchronous - The application register a callback using
+ * \li Asynchronous - The application registers a callback using
  *                    pa_stream_set_write_callback() and
  *                    pa_stream_set_read_callback() to receive notifications
  *                    that data can either be written or read.
@@ -222,9 +222,11 @@
  * accomplish that the pa_stream_write() function takes a seek mode
  * and an offset argument. The seek mode is one of:
  *
- * \li PA_SEEK_RELATIVE - seek relative to the current write index
- * \li PA_SEEK_ABSOLUTE - seek relative to the beginning of the playback buffer, (i.e. the first that was ever played in the stream)
- * \li PA_SEEK_RELATIVE_ON_READ - seek relative to the current read index. Use this to write data to the output buffer that should be played as soon as possible
+ * \li PA_SEEK_RELATIVE - seek relative to the current write index.
+ * \li PA_SEEK_ABSOLUTE - seek relative to the beginning of the playback buffer,
+ * (i.e. the first that was ever played in the stream).
+ * \li PA_SEEK_RELATIVE_ON_READ - seek relative to the current read index. Use
+ * this to write data to the output buffer that should be played as soon as possible.
  * \li PA_SEEK_RELATIVE_END - seek relative to the last byte ever written.
  *
  * If an application just wants to append some data to the output
@@ -309,10 +311,10 @@
  * been created -- uncork them all with a single call to
  * pa_stream_cork() for the master stream.
  *
- * To make sure that a particular stream doesn't stop to play when a
+ * To make sure that a particular stream doesn't stop playing when a
  * server side buffer underrun happens on it while the other
  * synchronized streams continue playing and hence deviate, you need to
- * pass a "prebuf" pa_buffer_attr of 0 when connecting it.
+ * pass a pa_buffer_attr with prebuf set to 0 when connecting.
  *
  * \section disc_sec Disconnecting
  *
@@ -396,7 +398,8 @@ pa_context* pa_stream_get_context(pa_stream *p);
 /** Return the sink input resp.\ source output index this stream is
  * identified in the server with. This is useful with the
  * introspection functions such as pa_context_get_sink_input_info()
- * or pa_context_get_source_output_info(). */
+ * or pa_context_get_source_output_info(). This returns PA_INVALID_INDEX
+ * on failure. */
 uint32_t pa_stream_get_index(pa_stream *s);
 
 /** Return the index of the sink or source this stream is connected to
@@ -406,8 +409,8 @@ uint32_t pa_stream_get_index(pa_stream *s);
  *
  * Please note that streams may be moved between sinks/sources and thus
  * it is recommended to use pa_stream_set_moved_callback() to be notified
- * about this. This function will return with -PA_ERR_NOTSUPPORTED when the
- * server is older than 0.9.8. \since 0.9.8 */
+ * about this. This function will return with PA_INVALID_INDEX on failure,
+ * including the being server older than 0.9.8. \since 0.9.8 */
 uint32_t pa_stream_get_device_index(pa_stream *s);
 
 /** Return the name of the sink or source this stream is connected to
@@ -417,8 +420,8 @@ uint32_t pa_stream_get_device_index(pa_stream *s);
  *
  * Please note that streams may be moved between sinks/sources and thus
  * it is recommended to use pa_stream_set_moved_callback() to be notified
- * about this. This function will return with -PA_ERR_NOTSUPPORTED when the
- * server is older than 0.9.8. \since 0.9.8 */
+ * about this. This function will fail when the server is older than
+ * 0.9.8. \since 0.9.8 */
 const char *pa_stream_get_device_name(pa_stream *s);
 
 /** Return 1 if the sink or source this stream is connected to has
@@ -454,7 +457,9 @@ int pa_stream_is_corked(pa_stream *s);
  *
  * Since 5.0, it's possible to specify a single-channel volume even if the
  * stream has multiple channels. In that case the same volume is applied to all
- * channels. */
+ * channels.
+ *
+ * Returns zero on success. */
 int pa_stream_connect_playback(
         pa_stream *s                  /**< The stream to connect to a sink */,
         const char *dev               /**< Name of the sink to connect to, or NULL for default */ ,
@@ -463,14 +468,14 @@ int pa_stream_connect_playback(
         const pa_cvolume *volume      /**< Initial volume, or NULL for default */,
         pa_stream *sync_stream        /**< Synchronize this stream with the specified one, or NULL for a standalone stream */);
 
-/** Connect the stream to a source. */
+/** Connect the stream to a source. Returns zero on success. */
 int pa_stream_connect_record(
         pa_stream *s                  /**< The stream to connect to a source */ ,
         const char *dev               /**< Name of the source to connect to, or NULL for default */,
         const pa_buffer_attr *attr    /**< Buffer attributes, or NULL for default */,
         pa_stream_flags_t flags       /**< Additional flags, or 0 for default */);
 
-/** Disconnect a stream from a source/sink. */
+/** Disconnect a stream from a source/sink. Returns zero on success. */
 int pa_stream_disconnect(pa_stream *s);
 
 /** Prepare writing data to the server (for playback streams). This
@@ -504,7 +509,14 @@ int pa_stream_disconnect(pa_stream *s);
  * pa_stream_write() use pa_stream_cancel_write(). Calling
  * pa_stream_begin_write() twice without calling pa_stream_write() or
  * pa_stream_cancel_write() in between will return exactly the same
- * \a data pointer and \a nbytes values. \since 0.9.16 */
+ * \a data pointer and \a nbytes values.
+ *
+ * On success, will return zero and a valid (non-NULL) pointer. If the
+ * return value is non-zero, or the pointer is NULL, this indicates an
+ * error. Callers should also pay careful attention to the returned
+ * length, which may not be the same as that passed in, as mentioned above.
+ *
+ * \since 0.9.16 */
 int pa_stream_begin_write(
         pa_stream *p,
         void **data,
@@ -517,8 +529,8 @@ int pa_stream_begin_write(
  * pa_stream_cancel_write() nor pa_stream_write() have been called
  * yet. Accessing the memory previously returned by
  * pa_stream_begin_write() after this call is invalid. Any further
- * explicit freeing of the memory area is not necessary. \since
- * 0.9.16 */
+ * explicit freeing of the memory area is not necessary.
+ * Returns zero on success. \since 0.9.16 */
 int pa_stream_cancel_write(
         pa_stream *p);
 
@@ -530,9 +542,9 @@ int pa_stream_cancel_write(
  *
  * The client may freely seek around in the output buffer. For
  * most applications it is typical to pass 0 and PA_SEEK_RELATIVE
- * as values for the arguments \a offset and \a seek. After the write
- * call succeeded the write index will be at the position after where
- * this chunk of data has been written to.
+ * as values for the arguments \a offset and \a seek respectively.
+ * After a successful write call 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
  * pa_stream_begin_write() before this call and then place your audio
@@ -540,10 +552,12 @@ int pa_stream_cancel_write(
  * a pointer to that memory area to pa_stream_write(). After the
  * invocation of pa_stream_write() the memory area may no longer be
  * accessed. Any further explicit freeing of the memory area is not
- * necessary. It is OK to write the memory area returned by
+ * necessary. It is OK to write to the memory area returned by
  * pa_stream_begin_write() only partially with this call, skipping
  * bytes both at the end and at the beginning of the reserved memory
- * area.*/
+ * area.
+ *
+ * Returns zero on success. */
 int pa_stream_write(
         pa_stream *p             /**< The stream to use */,
         const void *data         /**< The data to write */,
@@ -578,14 +592,16 @@ int pa_stream_write_ext_free(
  * Use pa_stream_drop() to actually remove the data from the buffer
  * and move the read index forward. pa_stream_drop() should not be
  * called if the buffer is empty, but it should be called if there is
- * a hole. */
+ * a hole.
+ *
+ * Returns zero on success, negative on error. */
 int pa_stream_peek(
         pa_stream *p                 /**< The stream to use */,
         const void **data            /**< Pointer to pointer that will point to data */,
         size_t *nbytes               /**< The length of the data read in bytes */);
 
 /** Remove the current fragment on record streams. It is invalid to do this without first
- * calling pa_stream_peek(). */
+ * calling pa_stream_peek(). Returns zero on success. */
 int pa_stream_drop(pa_stream *p);
 
 /** Return the number of bytes requested by the server that have not yet
@@ -595,10 +611,14 @@ int pa_stream_drop(pa_stream *p);
  * buffer_attr.maxlength bytes. This is usually not desirable, though, as
  * it would increase stream latency to be higher than requested
  * (buffer_attr.tlength).
+ *
+ * (size_t) -1 is returned on error.
  */
 size_t pa_stream_writable_size(pa_stream *p);
 
-/** Return the number of bytes that may be read using pa_stream_peek(). */
+/** Return the number of bytes that may be read using pa_stream_peek().
+ *
+ * (size_t) -1 is returned on error. */
 size_t pa_stream_readable_size(pa_stream *p);
 
 /** Drain a playback stream.  Use this for notification when the
@@ -635,7 +655,7 @@ int64_t pa_stream_get_underflow_index(pa_stream *p);
 /** Set the callback function that is called when a buffer underflow happens. (Only for playback streams) */
 void pa_stream_set_underflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
 
-/** Set the callback function that is called when a the server starts
+/** Set the callback function that is called when the server starts
  * playback after an underrun or on initial startup. This only informs
  * that audio is flowing again, it is no indication that audio started
  * to reach the speakers already. (Only for playback streams) \since
@@ -736,7 +756,9 @@ pa_operation* pa_stream_set_name(pa_stream *s, const char *name, pa_stream_succe
  *
  * If no timing information has been
  * received yet this call will return -PA_ERR_NODATA. For more details
- * see pa_stream_get_timing_info(). */
+ * see pa_stream_get_timing_info().
+ *
+ * Returns zero on success, negative on error. */
 int pa_stream_get_time(pa_stream *s, pa_usec_t *r_usec);
 
 /** Determine the total stream latency. This function is based on
@@ -757,14 +779,13 @@ int pa_stream_get_latency(pa_stream *s, pa_usec_t *r_usec, int *negative);
 
 /** Return the latest raw timing data structure. The returned pointer
  * refers to an internal read-only instance of the timing
- * structure. The user should make a copy of this structure if he
- * wants to modify it. An in-place update to this data structure may
- * be requested using pa_stream_update_timing_info().
+ * structure. The user should make a copy of this structure if
+ * wanting to modify it. An in-place update to this data structure
+ * may be requested using pa_stream_update_timing_info().
  *
  * If no timing information has been received before (i.e. by
  * requesting pa_stream_update_timing_info() or by using
- * PA_STREAM_AUTO_TIMING_UPDATE), this function will fail with
- * -PA_ERR_NODATA.
+ * PA_STREAM_AUTO_TIMING_UPDATE), this function will return NULL.
  *
  * Please note that the write_index member field (and only this field)
  * is updated on each pa_stream_write() call, not just when a timing
@@ -791,7 +812,7 @@ const pa_format_info* pa_stream_get_format_info(pa_stream *s);
 const pa_buffer_attr* pa_stream_get_buffer_attr(pa_stream *s);
 
 /** Change the buffer metrics of the stream during playback. The
- * server might have chosen different buffer metrics then
+ * server might have chosen different buffer metrics than
  * requested. The selected metrics may be queried with
  * pa_stream_get_buffer_attr() as soon as the callback is called. Only
  * valid after the stream has been connected successfully and if the
@@ -821,13 +842,13 @@ pa_operation *pa_stream_proplist_remove(pa_stream *s, const char *const keys[],
 
 /** For record streams connected to a monitor source: monitor only a
  * very specific sink input of the sink. This function needs to be
- * called before pa_stream_connect_record() is called. \since
- * 0.9.11 */
+ * called before pa_stream_connect_record() is called.
+ * Returns zero on success, negative on error. \since 0.9.11 */
 int pa_stream_set_monitor_stream(pa_stream *s, uint32_t sink_input_idx);
 
 /** Return the sink input index previously set with
- * pa_stream_set_monitor_stream().
- * \since 0.9.11 */
+ * pa_stream_set_monitor_stream(). Returns PA_INVALID_INDEX
+ * on failure. \since 0.9.11 */
 uint32_t pa_stream_get_monitor_stream(pa_stream *s);
 
 PA_C_DECL_END
diff --git a/src/pulse/thread-mainloop.h b/src/pulse/thread-mainloop.h
index e69298aa0..79c91eff0 100644
--- a/src/pulse/thread-mainloop.h
+++ b/src/pulse/thread-mainloop.h
@@ -37,7 +37,7 @@ PA_C_DECL_BEGIN
  *
  * The added feature in the threaded main loop is that it spawns a new thread
  * that runs the real main loop. This allows a synchronous application to use
- * the asynchronous API without risking to stall the PulseAudio library.
+ * the asynchronous API without risking stalling the PulseAudio library.
  *
  * \section creat_sec Creation
  *
@@ -247,7 +247,7 @@ typedef struct pa_threaded_mainloop pa_threaded_mainloop;
 
 /** Allocate a new threaded main loop object. You have to call
  * pa_threaded_mainloop_start() before the event loop thread starts
- * running. */
+ * running. Free with pa_threaded_mainloop_free. */
 pa_threaded_mainloop *pa_threaded_mainloop_new(void);
 
 /** Free a threaded main loop object. If the event loop thread is
@@ -255,7 +255,7 @@ pa_threaded_mainloop *pa_threaded_mainloop_new(void);
  * first. */
 void pa_threaded_mainloop_free(pa_threaded_mainloop* m);
 
-/** Start the event loop thread. */
+/** Start the event loop thread. Returns zero on success, negative on error. */
 int pa_threaded_mainloop_start(pa_threaded_mainloop *m);
 
 /** Terminate the event loop thread cleanly. Make sure to unlock the
diff --git a/src/pulse/utf8.c b/src/pulse/utf8.c
index 31a61a028..3262eed57 100644
--- a/src/pulse/utf8.c
+++ b/src/pulse/utf8.c
@@ -33,7 +33,7 @@
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.         See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
diff --git a/src/pulse/volume.h b/src/pulse/volume.h
index 08db7cfe3..2503c3f60 100644
--- a/src/pulse/volume.h
+++ b/src/pulse/volume.h
@@ -147,7 +147,9 @@ typedef struct pa_cvolume {
     pa_volume_t values[PA_CHANNELS_MAX];  /**< Per-channel volume */
 } pa_cvolume;
 
-/** Return non-zero when *a == *b */
+/** Return non-zero when *a == *b, checking that both a and b
+ * have the same number of channels and that the volumes of
+ * channels in a equal those in b. */
 int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE;
 
 /** Initialize the specified volume and return a pointer to
@@ -171,7 +173,7 @@ pa_cvolume* pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v);
  * might become part of an ABI.*/
 #define PA_CVOLUME_SNPRINT_MAX 320
 
-/** Pretty print a volume structure */
+/** Pretty print a volume structure. Returns \a s. */
 char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
 
 /** Maximum length of the strings returned by
@@ -181,7 +183,7 @@ char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
  * might become part of an ABI. \since 0.9.13 */
 #define PA_SW_CVOLUME_SNPRINT_DB_MAX 448
 
-/** Pretty print a volume structure but show dB values. \since 0.9.13 */
+/** Pretty print a volume structure, showing dB values. Returns \a s. \since 0.9.13 */
 char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c);
 
 /** Maximum length of the strings returned by pa_cvolume_snprint_verbose().
@@ -193,7 +195,7 @@ char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c);
 /** Pretty print a volume structure in a verbose way. The volume for each
  * channel is printed in several formats: the raw pa_volume_t value,
  * percentage, and if print_dB is non-zero, also the dB value. If map is not
- * NULL, the channel names will be printed. \since 5.0 */
+ * NULL, the channel names will be printed. Returns \a s. \since 5.0 */
 char *pa_cvolume_snprint_verbose(char *s, size_t l, const pa_cvolume *c, const pa_channel_map *map, int print_dB);
 
 /** Maximum length of the strings returned by
@@ -203,7 +205,7 @@ char *pa_cvolume_snprint_verbose(char *s, size_t l, const pa_cvolume *c, const p
  * might become part of an ABI. \since 0.9.15 */
 #define PA_VOLUME_SNPRINT_MAX 10
 
-/** Pretty print a volume \since 0.9.15 */
+/** Pretty print a volume. Returns \a s. \since 0.9.15 */
 char *pa_volume_snprint(char *s, size_t l, pa_volume_t v);
 
 /** Maximum length of the strings returned by
@@ -213,7 +215,7 @@ char *pa_volume_snprint(char *s, size_t l, pa_volume_t v);
  * might become part of an ABI. \since 0.9.15 */
 #define PA_SW_VOLUME_SNPRINT_DB_MAX 11
 
-/** Pretty print a volume but show dB values. \since 0.9.15 */
+/** Pretty print a volume but show dB values. Returns \a s. \since 0.9.15 */
 char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v);
 
 /** Maximum length of the strings returned by pa_volume_snprint_verbose().
@@ -224,7 +226,7 @@ char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v);
 
 /** Pretty print a volume in a verbose way. The volume is printed in several
  * formats: the raw pa_volume_t value, percentage, and if print_dB is non-zero,
- * also the dB value. \since 5.0 */
+ * also the dB value. Returns \a s. \since 5.0 */
 char *pa_volume_snprint_verbose(char *s, size_t l, pa_volume_t v, int print_dB);
 
 /** Return the average volume of all channels */
@@ -276,13 +278,13 @@ pa_volume_t pa_sw_volume_multiply(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
 
 /** Multiply two per-channel volumes and return the result in
  * *dest. This is only valid for software volumes! a, b and dest may
- * point to the same structure. */
+ * point to the same structure. Returns dest, or NULL on error. */
 pa_cvolume *pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
 
 /** Multiply a per-channel volume with a scalar volume and return the
  * result in *dest. This is only valid for software volumes! a
- * and dest may point to the same structure. \since
- * 0.9.16 */
+ * and dest may point to the same structure. Returns dest, or NULL on error.
+ * \since 0.9.16 */
 pa_cvolume *pa_sw_cvolume_multiply_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
 
 /** Divide two volume specifications, return the result. This uses
@@ -293,13 +295,14 @@ pa_volume_t pa_sw_volume_divide(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
 
 /** Divide two per-channel volumes and return the result in
  * *dest. This is only valid for software volumes! a, b
- * and dest may point to the same structure. \since 0.9.13 */
+ * and dest may point to the same structure. Returns dest,
+ * or NULL on error. \since 0.9.13 */
 pa_cvolume *pa_sw_cvolume_divide(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
 
 /** Divide a per-channel volume by a scalar volume and return the
  * result in *dest. This is only valid for software volumes! a
- * and dest may point to the same structure. \since
- * 0.9.16 */
+ * and dest may point to the same structure. Returns dest,
+ * or NULL on error. \since 0.9.16 */
 pa_cvolume *pa_sw_cvolume_divide_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
 
 /** Convert a decibel value to a volume (amplitude, not power). This is only valid for software volumes! */
@@ -308,8 +311,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.  0.0 and less is muted while
- * 1.0 is PA_VOLUME_NORM.  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! */
@@ -322,7 +325,8 @@ double pa_sw_volume_to_linear(pa_volume_t v) PA_GCC_CONST;
 #define PA_DECIBEL_MININFTY ((double) -200.0)
 #endif
 
-/** Remap a volume from one channel mapping to a different channel mapping. \since 0.9.12 */
+/** Remap a volume from one channel mapping to a different channel mapping.
+ * Returns \a v. \since 0.9.12 */
 pa_cvolume *pa_cvolume_remap(pa_cvolume *v, const pa_channel_map *from, const pa_channel_map *to);
 
 /** Return non-zero if the specified volume is compatible with the
@@ -348,7 +352,7 @@ float pa_cvolume_get_balance(const pa_cvolume *v, const pa_channel_map *map) PA_
  * requested balance value (e.g. when the input volume was zero anyway for
  * all channels). If no balance value is applicable to
  * this channel map the volume will not be modified. See
- * pa_channel_map_can_balance(). \since 0.9.15 */
+ * pa_channel_map_can_balance(). Will return NULL on error. \since 0.9.15 */
 pa_cvolume* pa_cvolume_set_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance);
 
 /** Calculate a 'fade' value (i.e.\ 'balance' between front and rear)
@@ -366,7 +370,7 @@ float pa_cvolume_get_fade(const pa_cvolume *v, const pa_channel_map *map) PA_GCC
  * return the requested fade value (e.g. when the input volume was
  * zero anyway for all channels). If no fade value is applicable to
  * this channel map the volume will not be modified. See
- * pa_channel_map_can_fade(). \since 0.9.15 */
+ * pa_channel_map_can_fade(). Will return NULL on error. \since 0.9.15 */
 pa_cvolume* pa_cvolume_set_fade(pa_cvolume *v, const pa_channel_map *map, float new_fade);
 
 /** Calculate a 'lfe balance' value for the specified volume with
@@ -384,25 +388,28 @@ float pa_cvolume_get_lfe_balance(const pa_cvolume *v, const pa_channel_map *map)
  * return the requested value (e.g. when the input volume was
  * zero anyway for all channels). If no lfe balance value is applicable to
  * this channel map the volume will not be modified. See
- * pa_channel_map_can_lfe_balance(). \since 8.0 */
+ * pa_channel_map_can_lfe_balance(). Will return NULL on error. \since 8.0 */
 pa_cvolume* pa_cvolume_set_lfe_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance);
 
 /** Scale the passed pa_cvolume structure so that the maximum volume
  * of all channels equals max. The proportions between the channel
- * volumes are kept. \since 0.9.15 */
+ * volumes are kept. Returns \a v, or NULL on error. \since 0.9.15 */
 pa_cvolume* pa_cvolume_scale(pa_cvolume *v, pa_volume_t max);
 
 /** Scale the passed pa_cvolume structure so that the maximum volume
  * of all channels selected via cm/mask equals max. This also modifies
  * the volume of those channels that are unmasked. The proportions
- * between the channel volumes are kept. \since 0.9.16 */
+ * between the channel volumes are kept. If cm is NULL this call is
+ * identical to pa_cvolume_scale(). Returns \a v, or NULL on error.
+ * \since 0.9.16 */
 pa_cvolume* pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, const pa_channel_map *cm, pa_channel_position_mask_t mask);
 
 /** Set the passed volume to all channels at the specified channel
  * position. Will return the updated volume struct, or NULL if there
  * is no channel at the position specified. You can check if a channel
  * map includes a specific position by calling
- * pa_channel_map_has_position(). \since 0.9.16 */
+ * pa_channel_map_has_position(). Returns \a cv, or NULL on error.
+ * \since 0.9.16 */
 pa_cvolume* pa_cvolume_set_position(pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t, pa_volume_t v);
 
 /** Get the maximum volume of all channels at the specified channel
@@ -413,19 +420,21 @@ pa_volume_t pa_cvolume_get_position(pa_cvolume *cv, const pa_channel_map *map, p
 
 /** This goes through all channels in a and b and sets the
  * corresponding channel in dest to the greater volume of both. a, b
- * and dest may point to the same structure. \since 0.9.16 */
+ * and dest may point to the same structure. Returns \a dest, or NULL
+ * on error. \since 0.9.16 */
 pa_cvolume* pa_cvolume_merge(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
 
 /** Increase the volume passed in by 'inc', but not exceeding 'limit'.
- * The proportions between the channels are kept. \since 0.9.19 */
+ * The proportions between the channels are kept.
+ * Returns \a v, or NULL on error. \since 0.9.19 */
 pa_cvolume* pa_cvolume_inc_clamp(pa_cvolume *v, pa_volume_t inc, pa_volume_t limit);
 
 /** Increase the volume passed in by 'inc'. The proportions between
- * the channels are kept. \since 0.9.16 */
+ * the channels are kept. Returns \a v, or NULL on error. \since 0.9.16 */
 pa_cvolume* pa_cvolume_inc(pa_cvolume *v, pa_volume_t inc);
 
 /** Decrease the volume passed in by 'dec'. The proportions between
- * the channels are kept. \since 0.9.16 */
+ * the channels are kept. Returns \a v, or NULL on error. \since 0.9.16 */
 pa_cvolume* pa_cvolume_dec(pa_cvolume *v, pa_volume_t dec);
 
 PA_C_DECL_END