[pulseaudio-discuss] [PATCH] describe proplist return values and clarification

[Peter Meerwald]

From: Peter Meerwald <p.meerwald at bct-electronic.com>

ATTENTION: pa_proplist_unset() and pa_proplist_contains() have unconventional
return codes (-2/-1/0) and -1/0/1, resp.); this aims to document the current
behaviour, however, it might as well be a bug...
---
 src/pulse/proplist.h |   13 ++++++++-----
 1 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/pulse/proplist.h b/src/pulse/proplist.h
index b95cfc9..de48634 100644
--- a/src/pulse/proplist.h
+++ b/src/pulse/proplist.h
@@ -311,8 +311,8 @@ int pa_proplist_set(pa_proplist *p, const char *key, const void *data, size_t nb
  * the data before accessing the property list again. \since 0.9.11 */
 const char *pa_proplist_gets(pa_proplist *p, const char *key);
 
-/** Return the the value for the specified key. Will return a
- * NUL-terminated string for string entries. The pointer returned will
+/** Store the value for the specified key in \a data. Will store a
+ * NUL-terminated string for string entries. The \a data pointer 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 */
@@ -346,7 +346,9 @@ typedef enum pa_update_mode {
 void pa_proplist_update(pa_proplist *p, pa_update_mode_t mode, 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 0 if the key has been removed, -1 if the
+ * key name is invalid, or -2 if the key does not exist in the property
+ * list.\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
@@ -383,14 +385,15 @@ 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, 0 if such an entry does not exist, or -1 if the key
+ * is invalid. \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 */
 void pa_proplist_clear(pa_proplist *p);
 
 /** Allocate a new property list and copy over every single entry from
- * the specific list. \since 0.9.11 */
+ * the specified list. \since 0.9.11 */
 pa_proplist* pa_proplist_copy(pa_proplist *p);
 
 /** Return the number of entries in the property list. \since 0.9.15 */
-- 
1.7.4.1