comment the transaction private structure better

1 files changed, 45 insertions, 5 deletions

diff --git a/src/pop-transaction.c b/src/pop-transaction.c
index e199a5c..d356b24 100644
--- a/src/pop-transaction.c
+++ b/src/pop-transaction.c
@@ -38,27 +38,67 @@ typedef enum
 
 struct _PopTransactionPrivate
 {
+  /* The transaction state is what the transaction
+   * is currently doing, where as the status is
+   * just whether its still pending, succeeded, or
+   * failed.  The state is used internally, whereas
+   * the status is for the user of the api.
+   */
   PopTransactionState state;
   PopTransactionStatus status;
 
-  /* FIXME: might be better to keep this as a tree to
-   * catch dependencies when one action adds another
+  /* Actions get run sequentially, returning to the event
+   * loop in between. Actions are set up by the user of the
+   * transaction api, or potentially by other actions during 
+   * the run.
    */
   GQueue *actions;
   GList  *current_action_node;
 
-  GClosure *completion_closure;
+  /* which event loop to hook up with.  This is normally NULL,
+   * which means "use the default context".
+   */
   GMainContext *context;
 
-  guint is_in_action : 1;
-
+  /* state variable that means an action is running right now;
+   * the api function getting called is getting called from
+   * within an action handler
+   */
+  guint is_running_action : 1;
+
+  /* we process actions with an idle handler.  We do one action
+   * each time the idle handler is dispatched.  These ids are
+   * used for removing the idle handler later.  For instance, if
+   * the transaction gets paused temporarily by an action, then
+   * we would cancel the idle handler and recreate it when the
+   * transaction gets unpaused.
+   */
   guint process_idle_id;
   guint rollback_idle_id;
+
+  /* two common reasons to want to pause a transaction
+   * temporarily are to 1) wait for a timeout 2) wait for
+   * activity on a file descriptor.  Since they seem like pretty
+   * common things to want to do, we provide convenience
+   * functions for doing them.  The convenience functions use
+   * a timeout source and an io watch source respectively.
+   * wait_id is id of one these sources when they are attached
+   * to the event loop context.
+   */
   guint wait_id;
 
+  /* when the transaction finishes there needs to be a way to
+   * extract the output of the transaction.  Rather than forcing
+   * the user of the api to come up some ad-hoc way of moving
+   * the result from the last action to caller of the
+   * transaction, we provide an api to do it.
+   */
   gpointer result;
   GDestroyNotify free_result_func;
 
+  /* when an action fails the transaction it can optionally set
+   * an error on why it failed the transaction
+   */
   GError *error;
 };