Index: gam_subscription.c
===================================================================
RCS file: /cvs/gnome/gamin/server/gam_subscription.c,v
retrieving revision 1.14
diff -u -r1.14 gam_subscription.c
--- gam_subscription.c	9 May 2005 13:45:55 -0000	1.14
+++ gam_subscription.c	14 Jun 2005 14:41:12 -0000
@@ -47,37 +47,34 @@
  * @ingroup Daemon
  * @brief GamSubscription API.
  *
- * A #GamSubscription represents a single monitoring request (or "subscription").
+ * A #GamSubscription represents a single monitoring request (i.e. a
+ * subscription to a file or directory).
  *
  * @{
  */
 
 /**
- * Creates a new GamSubscription
+ * gam_subscription_new:
+ * @path: the path to be monitored
+ * @events: the events that are accepted to which GAMIN_EVENT_EXISTS
+ * and GAMIN_EVENT_ENDEXISTS are implicitly added
+ * @reqno: the request number to associate with the subscription
+ * @is_dir: whether the subscription is for a directory or a file
+ * @options: the options to enable for this subscription
  *
- * @param path the path to be monitored
- * @param events the events that are accepted
- * @param is_dir whether the subscription is for a directory or not
- * @returns the new GamSubscription
+ * Returns a new #GamSubscription
  */
 GamSubscription *
-gam_subscription_new(const char *path,
-                     int events,
-                     int reqno,
-                     gboolean is_dir,
+gam_subscription_new(const char *path, int events, int reqno, gboolean is_dir,
 		     int options)
 {
     GamSubscription *sub;
 
     sub = g_new0(GamSubscription, 1);
     sub->path = g_strdup(path);
-    sub->events = events;
+    sub->events = events | GAMIN_EVENT_EXISTS | GAMIN_EVENT_ENDEXISTS;
     sub->reqno = reqno;
     sub->pathlen = strlen(path);
-
-    /* everyone accepts this */
-    gam_subscription_set_event(sub, GAMIN_EVENT_EXISTS | GAMIN_EVENT_ENDEXISTS);
-
     sub->is_dir = is_dir;
     sub->options = options;
 
@@ -86,212 +83,218 @@
 }
 
 /**
- * Frees a GamSubscription
+ * gam_subscription_free:
+ * @sub: a #GamSubscription
  *
- * @param sub the GamSubscription
+ * Free a #GamSubscription allocated by gam_subscription_new.
  */
 void
 gam_subscription_free(GamSubscription * sub)
 {
-    if (sub == NULL)
-        return;
     GAM_DEBUG(DEBUG_INFO, "Freeing subscription for %s\n", sub->path);
+    g_assert(sub);
 
     g_free(sub->path);
     g_free(sub);
 }
 
 /**
- * Tells if a GamSubscription is for a directory or not
+ * gam_subscription_is_dir:
+ * @sub: a #GamSubscription
  *
- * @param sub the GamSubscription
- * @returns TRUE if the subscription is for a directory, FALSE otherwise
+ * Returns whether the subscription is for a directory.
  */
 gboolean
 gam_subscription_is_dir(GamSubscription * sub)
 {
-    if (sub == NULL)
-        return(FALSE);
+    g_assert(sub);
     return sub->is_dir;
 }
 
 /**
- * Provide the path len for a GamSubscription
+ * gam_subscription_pathlen:
+ * @sub: a #GamSubscription
  *
- * @param sub the GamSubscription
- * @returns the path len for the subscription
+ * Returns the length of the path of a #GamSubscription
  */
 int
 gam_subscription_pathlen(GamSubscription * sub)
 {
-    if (sub == NULL)
-        return(-1);
+    g_assert(sub);
     return sub->pathlen;
 }
 
 /**
- * Gets the path for a GamSubscription
+ * gam_subscription_get_path:
+ * @sub: a #GamSubscription
  *
- * @param sub the GamSubscription
- * @returns The path being monitored.  It should not be freed.
+ * Returns the path of a #GamSubscription.  The caller must not free
+ * the path and if it wants to hold on to it must either maintain a
+ * reference to the #GamSubscription or make a copy of the string.
  */
 G_CONST_RETURN char *
 gam_subscription_get_path(GamSubscription * sub)
 {
-    if (sub == NULL)
-        return(NULL);
+    g_assert(sub);
     return sub->path;
 }
 
 /**
- * Gets the request number for a GamSubscription
+ * gam_subscription_get_reqno:
+ * @sub: a #GamSubscription
  *
- * @param sub the GamSubscription
- * @returns The request number
+ * Returns the request number of a #GamSubscription
  */
 int
 gam_subscription_get_reqno(GamSubscription * sub)
 {
-    if (sub == NULL)
-        return(-1);
+    g_assert(sub);
     return sub->reqno;
 }
 
 /**
- * Gets the GamListener which owns this GamSubscription
+ * gam_subscription_get_listener:
+ * @sub: a #GamSubscription
  *
- * @param sub the GamSubscription
- * @returns the GamListener, or NULL
+ * Returns the #GamListener which owns the #GamSubscription.  If no
+ * listener has yet been set using gam_subscription_set_listener,
+ * returns NULL.
  */
 GamListener *
 gam_subscription_get_listener(GamSubscription * sub)
 {
-    if (sub == NULL)
-        return(NULL);
+    g_assert(sub);
     return sub->listener;
 }
 
 /**
- * Sets the GamListener which is owned by this GamSubscription
+ * gam_subscription_set_listener:
+ * @sub: a #GamSubscription
+ * @listener: a #GamListener
  *
- * @param sub the GamSubscription
- * @param listener the GamListener
+ * Sets the GamListener which own the #GamSubscription.
  */
 void
 gam_subscription_set_listener(GamSubscription * sub,
-                              GamListener * listener)
+                              GamListener *listener)
 {
-    if (sub == NULL)
-        return;
     GAM_DEBUG(DEBUG_INFO, "Setting subscription listener for %s\n", sub->path);
+    g_assert(sub);
+    g_assert(listener);
     sub->listener = listener;
 }
 
 /**
- * Set the events this GamSubscription is interested in
+ * gam_subscription_set_event:
+ * @sub: a #GamSubscription
+ * @event: an ORed combination of the events to accept
  *
- * @param sub the GamSubscription
- * @param event an ORed combination of the events desired
+ * Sets events a #GamSubscription is interested in
  */
 void
 gam_subscription_set_event(GamSubscription * sub, int event)
 {
-    if (sub == NULL)
-        return;
+    g_assert(sub);
     sub->events |= event;
 }
 
 /**
- * Removes an event from the set of acceptable events
+ * gam_subscription_unset_event:
+ * @sub: a #GamSubscription
+ * @event: an ORed combination of the events to stop accepting
  *
- * @param sub the GamSubscription
- * @param event the event to remove
+ * Removes events from the set of events a #GamSubscription is
+ * interested in
  */
 void
 gam_subscription_unset_event(GamSubscription * sub, int event)
 {
-    if (sub == NULL)
-        return;
+    g_assert(sub);
     sub->events &= ~event;
 }
 
 /**
- *  
- * @param sub the GamSubscription
- * @param event the event to test for
- * @returns Whether or not this subscription accepts a given event
+ * gam_subscription_has_event:
+ * @sub: a #GamSubscription
+ * @event: an event to test for
+ *
+ * Returns whether the subscription accepts an event
  */
 gboolean
 gam_subscription_has_event(GamSubscription * sub, int event)
 {
-    if (sub == NULL)
-        return(FALSE);
+    g_assert(sub);
+    g_assert((event & (event - 1)) == 0);
     return((sub->events & event) != 0);
 }
 
 /**
- *  
- * @param sub the GamSubscription
- * @option option
- * @returns Whether or not this subscription has that option.
+ * gam_subscription_has_option:
+ * @sub: the #GamSubscription
+ * @option: an option
+ *
+ * Returns whether the subscription has the option enabled
  */
 gboolean
 gam_subscription_has_option(GamSubscription * sub, int option)
 {
-    if (sub == NULL)
-        return(FALSE);
+    g_assert(sub);
+    g_assert((option & (option - 1)) == 0);
     return((sub->options & option) != 0);
 }
 
 /**
- * Mark this GamSubscription as cancelled
- *
+ * gam_subscription_cancel:
  * @param sub the GamSubscription
+ *
+ * Mark a #GamSubscription as cancelled
  */
 void
 gam_subscription_cancel(GamSubscription * sub)
 {
-    if (sub == NULL)
-        return;
     GAM_DEBUG(DEBUG_INFO, "Cancelling subscription for %s\n", sub->path);
+    g_assert(sub);
     sub->cancelled = TRUE;
 }
 
 /**
- * Checks if the GamSubscription is cancelled or not
+ * gam_subscription_is_cancelled:
+ * @sub: a #GamSubscription
  *
- * @param sub the GamSubscription
- * @returns TRUE if the GamSubscription is cancelled, FALSE otherwise
+ * Returns whether a #GamSubscription is cancelled
  */
 gboolean
 gam_subscription_is_cancelled(GamSubscription * sub)
 {
-    if (sub == NULL)
-        return(TRUE);
+    g_assert(sub);
     return sub->cancelled == TRUE;
 }
 
 /**
  * gam_subscription_wants_event:
- * @sub: the GamSubscription
- * @name: file name (just the base name, not the complete path)
- * @is_dir_node: is the target a directory
- * @event: the event
+ * @sub: a #GamSubscription
+ * @name: the file on which the even occured (just the base name, not
+ * the complete path)
+ * @is_dir_node: if the event occured on a directory node
+ * @event: an event
  * @force: force the event as much as possible
  *
- * Checks if a given path/event combination is accepted by this GamSubscription
+ * Checks if a given path and event combination is accepted by a
+ * #GamSubscription
  *
- * Returns TRUE if the combination is accepted, FALSE otherwise
+ * Returns whether the combination is accepted
  */
 gboolean
 gam_subscription_wants_event(GamSubscription * sub,
                              const char *name, int is_dir_node, 
 			     GaminEventType event, int force)
 {
-    int same_path = 0;
+    int same_path;
+
+    g_assert(sub);
+    g_assert(name);
+    g_assert((event & (event - 1)) == 0);
 
-    if ((sub == NULL) || (name == NULL) || (event == 0))
-        return(FALSE);
     if (sub->cancelled)
         return FALSE;
 
@@ -303,7 +306,7 @@
     /* only directory listening cares for other files */
     same_path = !strcmp(name, sub->path);
     if ((sub->is_dir == 0) && (!same_path))
-        return(FALSE);
+        return FALSE;
 
     if (!gam_subscription_has_event(sub, event)) {
         return FALSE;
@@ -311,6 +314,7 @@
 
     if (force)
         return TRUE;
+
     if ((sub->is_dir) && (is_dir_node) && (same_path)) {
         if ((event == GAMIN_EVENT_EXISTS) ||
 	    (event == GAMIN_EVENT_CHANGED) ||
@@ -323,12 +327,13 @@
 
 /**
  * gam_subscription_debug:
- * @sub: the subscription
+ * @sub: a #GamSubscription
  *
- * Provide debug output for that subscription node/state
+ * Print some debugging output about a subscription
  */
 void
-gam_subscription_debug(GamSubscription *sub) {
+gam_subscription_debug(GamSubscription * sub)
+{
 #ifdef GAM_DEBUG_ENABLED
     if (sub == NULL) {
 	GAM_DEBUG(DEBUG_INFO, "    Subscription is NULL\n");