From 8c12929b910b59fa86e208f1ca814550da10bbfc Mon Sep 17 00:00:00 2001
From: chme <christian.meffert@googlemail.com>
Date: Thu, 21 May 2015 07:57:18 +0200
Subject: [PATCH] Added source code comments, return error value if
 adding/removing a listener failed

---
 src/listener.c | 15 ++++++++-------
 src/listener.h | 30 +++++++++++++++++++++++++++++-
 src/player.h   |  5 ++++-
 3 files changed, 41 insertions(+), 9 deletions(-)

diff --git a/src/listener.c b/src/listener.c
index 0c4a7cec..92b575ba 100644
--- a/src/listener.c
+++ b/src/listener.c
@@ -21,7 +21,6 @@
 #include <unistd.h>
 #include <string.h>
 
-#include "logger.h"
 #include "listener.h"
 
 struct listener
@@ -39,6 +38,10 @@ listener_add(notify notify_cb, short events)
   struct listener *listener;
 
   listener = (struct listener*)malloc(sizeof(struct listener));
+  if (!listener)
+    {
+      return -1;
+    }
   listener->notify_cb = notify_cb;
   listener->events = events;
   listener->next = listener_list;
@@ -63,7 +66,9 @@ listener_remove(notify notify_cb)
     }
 
   if (!listener)
-    return 0;
+    {
+      return -1;
+    }
 
   if (prev)
     prev->next = listener->next;
@@ -74,13 +79,11 @@ listener_remove(notify notify_cb)
   return 0;
 }
 
-int
+void
 listener_notify(enum listener_event_type type)
 {
   struct listener *listener;
 
-  DPRINTF(E_DBG, L_MPD, "Notify event type %d\n", type);
-
   listener = listener_list;
   while (listener)
     {
@@ -88,6 +91,4 @@ listener_notify(enum listener_event_type type)
 	listener->notify_cb(type);
       listener = listener->next;
     }
-
-  return 0;
 }
diff --git a/src/listener.h b/src/listener.h
index 7fffe37a..8b493552 100644
--- a/src/listener.h
+++ b/src/listener.h
@@ -4,23 +4,51 @@
 
 enum listener_event_type
 {
+  /* The player has been started, stopped or seeked */
   LISTENER_PLAYER    = (1 << 0),
+  /* The current playlist has been modified */
   LISTENER_PLAYLIST  = (1 << 1),
+  /* The volume has been changed */
   LISTENER_VOLUME    = (1 << 2),
+  /* A speaker has been enabled or disabled */
   LISTENER_SPEAKER   = (1 << 3),
+  /* Options like repeat, random has been changed */
   LISTENER_OPTIONS   = (1 << 4),
+  /* The library has been modified */
   LISTENER_DATABASE  = (1 << 5),
 };
 
 typedef void (*notify)(enum listener_event_type type);
 
+/*
+ * Registers the given callback function to the given event types.
+ * This function is not thread safe. Listeners must be added once at startup.
+ *
+ * @param notify_cb Callback function
+ * @param events Event mask, one or more of LISTENER_*
+ * @return 0 on success, -1 on failure
+ */
 int
 listener_add(notify notify_cb, short events);
 
+/*
+ * Removes the given callback function
+ * This function is not thread safe. Listeners must be removed once at shutdown.
+ *
+ * @param notify_cb Callback function
+ * @return 0 on success, -1 if the callback was not registered
+ */
 int
 listener_remove(notify notify_cb);
 
-int
+/*
+ * Calls the callback function of the registered listeners listening for the
+ * given type of event.
+ *
+ * @param type The event type, on of the LISTENER_* values
+ *
+ */
+void
 listener_notify(enum listener_event_type type);
 
 #endif /* !__LISTENER_H__ */
diff --git a/src/player.h b/src/player.h
index f21ab1d5..8be2168c 100644
--- a/src/player.h
+++ b/src/player.h
@@ -54,7 +54,10 @@ struct player_status {
 
   /* Playlist id */
   uint32_t plid;
-  /* Playlist version */
+  /* Playlist version
+     After startup plversion is 0 and gets incremented after each change of the playlist
+     (e. g. after adding/moving/removing items). It is used by mpd clients to recognize if
+     they need to update the current playlist. */
   uint32_t plversion;
   /* Playlist length */
   uint32_t playlistlength;