Added documentation for join_on functions.

diff --git a/src/aop-main.c b/src/aop-main.c
index f8b4506a82047959dafeea5914be5722a3707b67..beac84191b5cb5821bc527ec4e47e9803dafefdd 100644 (file)
--- a/src/aop-main.c
+++ b/src/aop-main.c
@@ -76,6 +76,25 @@ regimplify ()
     }
 }
 
+/**
+ * Iterate over the join points in a pointcut.  The join calls the
+ * supplied callback once for each join point, passing the join point
+ * itself and the callback_param value.
+ *
+ * The callback can use capture functions to get information about the
+ * join point and aop_insert_advice() to actually instrument the join
+ * point.
+ *
+ * Join points are only valid for the lifetime of the callback.  When
+ * the callback finishes, the join point is deallocated and any
+ * attempt to access it is an error.
+ *
+ * \param pc The pointcut to iterate over.
+ * \param callback The callback to call for each join point.  The
+ * callback function should have a prototype that matches
+ * #join_callback.
+ * \param callback_param Any data you wish to pass to the callback.
+ */
 void
 aop_join_on (struct aop_pointcut *pc, join_callback callback, 
             void *callback_param)
@@ -91,6 +110,26 @@ aop_join_on (struct aop_pointcut *pc, join_callback callback,
   }
 }
 
+/**
+ * Iterate over the join points in a pointcut for a single copy of a
+ * duplicated function.  Calling aop_join_on() without duplicating the
+ * function first will result in an error.  Functions are duplicated
+ * with aop_duplicate().
+ *
+ * This kind of join works just like aop_join_on(), but all join
+ * points are within one copy of the function body.  It is guaranteed
+ * that advice inserted in one copy of a function body will only
+ * execute if that copy is chosen by the distributor, even for
+ * function entry and function exit join points.
+ *
+ * \param pc The pointcut to iterate over.
+ * \param copy The copy to iterate over: zero for the original copy,
+ * non-zero for the new copy.
+ * \param callback The callback to call for each join point.  The
+ * callback function should have a prototype that matches
+ * #join_callback.
+ * \param callback_param Any data you wish to pass to the callback.
+ */
 void
 aop_join_on_copy (struct aop_pointcut *pc, int copy, join_callback callback,
                  void *callback_param)