implement proper refcounting in polyplib

split polyplib to multiple modules
add some prelimenary documentation
add doxygen support


git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@123 fefdeb5f-60dc-0310-8127-8f9354f1896f

1 files changed, 30 insertions, 14 deletions

diff --git a/polyp/mainloop-api.h b/polyp/mainloop-api.h
index 1b9e2783..97ab6a68 100644
--- a/polyp/mainloop-api.h
+++ b/polyp/mainloop-api.h
@@ -22,26 +22,37 @@
   USA.
 ***/
 
-#include <time.h>
 #include <sys/time.h>
+#include <time.h>
 
-#ifdef __cplusplus
-extern "C" {
-#endif
+#include "cdecl.h"
 
+PA_C_DECL_BEGIN
+
+/** A bitmask for IO events */
 enum pa_io_event_flags {
-    PA_IO_EVENT_NULL = 0,
-    PA_IO_EVENT_INPUT = 1,
-    PA_IO_EVENT_OUTPUT = 2,
-    PA_IO_EVENT_HANGUP = 4,
-    PA_IO_EVENT_ERROR = 8,
+    PA_IO_EVENT_NULL = 0,     /**< No event */
+    PA_IO_EVENT_INPUT = 1,    /**< Input event */
+    PA_IO_EVENT_OUTPUT = 2,   /**< Output event */
+    PA_IO_EVENT_HANGUP = 4,   /**< Hangup event */
+    PA_IO_EVENT_ERROR = 8,    /**< Error event */
 };
 
+/** \struct pa_io_event
+ * An IO event source object */
 struct pa_io_event;
+
+/** \struct pa_defer_event
+ * A deferred event source object. Events of this type are triggered once in every main loop iteration */
 struct pa_defer_event;
+
+/** \struct pa_time_event
+ * A timer event source object */
 struct pa_time_event;
 
+/** An abstract mainloop API vtable */
 struct pa_mainloop_api {
+    /** A pointer to some private, arbitrary data of the main loop implementation */
     void *userdata;
 
     /* IO sources */
@@ -56,20 +67,25 @@ struct pa_mainloop_api {
     void (*time_free)(struct pa_time_event* e);
     void (*time_set_destroy)(struct pa_time_event *e, void (*callback) (struct pa_mainloop_api*a, struct pa_time_event *e, void *userdata));
 
-    /* Deferred sources */
+    /** Create a new deferred event source object */
     struct pa_defer_event* (*defer_new)(struct pa_mainloop_api*a, void (*callback) (struct pa_mainloop_api*a, struct pa_defer_event* e, void *userdata), void *userdata);
+
+    /** Enable or disable a deferred event source temporarily */
     void (*defer_enable)(struct pa_defer_event* e, int b);
+
+    /** Free a deferred event source object */
     void (*defer_free)(struct pa_defer_event* e);
+
+    /** Set a function that is called when the deferred event source is destroyed. Use this to free the userdata argument if required */
     void (*defer_set_destroy)(struct pa_defer_event *e, void (*callback) (struct pa_mainloop_api*a, struct pa_defer_event *e, void *userdata));
 
-    /* Exit mainloop */
+    /** Exit the main loop and return the specfied retval*/
     void (*quit)(struct pa_mainloop_api*a, int retval);
 };
 
+/** Run the specified callback function once from the main loop using an anonymous defer event. */
 void pa_mainloop_api_once(struct pa_mainloop_api*m, void (*callback)(struct pa_mainloop_api*m, void *userdata), void *userdata);
 
-#ifdef __cplusplus
-}
-#endif
+PA_C_DECL_END
 
 #endif