More documentation for finalization feature

6 files changed, 45 insertions, 10 deletions

diff --git a/bufferevent-internal.h b/bufferevent-internal.h
index 09cdb351..9ecede17 100644
--- a/bufferevent-internal.h
+++ b/bufferevent-internal.h
@@ -252,11 +252,13 @@ struct bufferevent_ops {
 	 */
 	int (*disable)(struct bufferevent *, short);
 
-	/** DOCUMENT */
+	/** Detatches the bufferevent from related data structures. Called as
+	 * soon as its reference count reaches 0. */
 	void (*unlink)(struct bufferevent *);
 
 	/** Free any storage and deallocate any extra data or structures used
-	    in this implementation. DOCUMENT
+	    in this implementation. Called when the bufferevent is
+	    finalized.
 	 */
 	void (*destruct)(struct bufferevent *);
 
diff --git a/bufferevent_openssl.c b/bufferevent_openssl.c
index 48c61c08..1ce124f9 100644
--- a/bufferevent_openssl.c
+++ b/bufferevent_openssl.c
@@ -1193,8 +1193,8 @@ be_openssl_unlink(struct bufferevent *bev)
 				    "bufferevent with too few references");
 			} else {
 				bufferevent_free(bev_ssl->underlying);
-				/* We still have a reference to it, since DOCUMENT. So we don't
-				 * drop this. */
+				/* We still have a reference to it, via our
+				 * BIO. So we don't drop this. */
 				// bev_ssl->underlying = NULL;
 			}
 		}
diff --git a/event-internal.h b/event-internal.h
index 07d29e32..bce96df5 100644
--- a/event-internal.h
+++ b/event-internal.h
@@ -59,15 +59,28 @@ extern "C" {
 #define ev_callback ev_evcallback.evcb_cb_union.evcb_callback
 #define ev_arg ev_evcallback.evcb_arg
 
-/* Possible values for evcb_closure in struct event_callback */
-/* DOCUMENT these. */
+/** @name Event closure codes
+
+    Possible values for evcb_closure in struct event_callback
+
+    @{
+ */
+/** A regular event. Uses the evcb_callback callback */
 #define EV_CLOSURE_EVENT 0
+/** A signal event. Uses the evcb_callback callback */
 #define EV_CLOSURE_EVENT_SIGNAL 1
+/** A persistent non-signal event. Uses the evcb_callback callback */
 #define EV_CLOSURE_EVENT_PERSIST 2
+/** A simple callback. Uses the evcb_selfcb callback. */
 #define EV_CLOSURE_CB_SELF 3
+/** A finalizing callback. Uses the evcb_cbfinalize callback. */
 #define EV_CLOSURE_CB_FINALIZE 4
+/** A finalizing event. Uses the evcb_evfinalize callback. */
 #define EV_CLOSURE_EVENT_FINALIZE 5
+/** A finalizing event that should get freed after. Uses the evcb_evfinalize
+ * callback. */
 #define EV_CLOSURE_EVENT_FINALIZE_FREE 6
+/** @} */
 
 /** Structure to define the backend of a given event_base. */
 struct eventop {
@@ -386,9 +399,19 @@ int evsig_restore_handler_(struct event_base *base, int evsignal);
 
 int event_add_nolock_(struct event *ev,
     const struct timeval *tv, int tv_is_absolute);
+/** Argument for event_del_nolock_. Tells event_del not to block on the event
+ * if it's running in another thread. */
 #define EVENT_DEL_NOBLOCK 0
+/** Argument for event_del_nolock_. Tells event_del to block on the event
+ * if it's running in another thread, regardless of its value for EV_FINALIZE
+ */
 #define EVENT_DEL_BLOCK 1
+/** Argument for event_del_nolock_. Tells event_del to block on the event
+ * if it is running in another thread and it doesn't have EV_FINALIZE set.
+ */
 #define EVENT_DEL_AUTOBLOCK 2
+/** Argument for event_del_nolock_. Tells event_del to procede even if the
+ * event is set up for finalization rather for regular use.*/
 #define EVENT_DEL_EVEN_IF_FINALIZING 3
 int event_del_nolock_(struct event *ev, int blocking);
 int event_remove_timer_nolock_(struct event *ev);
diff --git a/event.c b/event.c
index 0722fad5..6b8c3c5b 100644
--- a/event.c
+++ b/event.c
@@ -2599,8 +2599,11 @@ event_del_noblock(struct event *ev)
 	return event_del_(ev, EVENT_DEL_NOBLOCK);
 }
 
-/* Helper for event_del: always called with th_base_lock held.
- * DOCUMENT blocking */
+/** Helper for event_del: always called with th_base_lock held.
+ *
+ * "blocking" must be one of the EVENT_DEL_{BLOCK, NOBLOCK, AUTOBLOCK,
+ * EVEN_IF_FINALIZING} values. See those for more information.
+ */
 int
 event_del_nolock_(struct event *ev, int blocking)
 {
diff --git a/include/event2/event.h b/include/event2/event.h
index 3dfce377..4a63765c 100644
--- a/include/event2/event.h
+++ b/include/event2/event.h
@@ -599,12 +599,16 @@ struct event_base *event_base_new_with_config(const struct event_config *);
   Note that this function will not close any fds or free any memory passed
   to event_new as the argument to callback.
 
+  If there are any pending finalizer callbacks, this function will invoke
+  them.
 
   @param eb an event_base to be freed
  */
 void event_base_free(struct event_base *);
 
-/** DOCUMENT */
+/**
+   As event_free, but do not run finalizers.
+ */
 void event_base_free_nofinalize(struct event_base *);
 
 /** @name Log severities
@@ -1038,6 +1042,10 @@ typedef void (*event_finalize_callback_fn)(struct event *, void *);
 
    The event_free_finalize() function frees the event after it's finalized;
    event_finalize() does not.
+
+   A finalizer callback must not make events pending or active.  It must not
+   add events, activate events, or attempt to "resucitate" the event being
+   finalized in any way.
  */
 /**@{*/
 void event_finalize(unsigned, struct event *, event_finalize_callback_fn);
diff --git a/include/event2/event_struct.h b/include/event2/event_struct.h
index ad2403ec..1c8b71b6 100644
--- a/include/event2/event_struct.h
+++ b/include/event2/event_struct.h
@@ -105,7 +105,6 @@ struct name {								\
 struct event;
 
 struct event_callback {
-	/* DOCUMENT all these fields */
 	TAILQ_ENTRY(event_callback) evcb_active_next;
 	short evcb_flags;
 	ev_uint8_t evcb_pri;	/* smaller numbers are higher priority */