Updated docs for in_params.

diff --git a/src/aop-pointcut.c b/src/aop-pointcut.c
index c4f23e144ec7316134dd7e1efdef631fbac1e34a..f53c80f63a8077ea2bec86fc239a6326602c0d2d 100644 (file)
--- a/src/aop-pointcut.c
+++ b/src/aop-pointcut.c
@@ -36,6 +36,11 @@
 #include "aop-pointcut.h"
 #include "aop-type.h"
 
+/**
+ * \defgroup all_pc Functions for All Pointcuts
+ * \{
+ */
+
 /* Allocates a pointcut and initializes it with default values. */
 struct aop_pointcut *
 create_pointcut (enum aop_pckind kind)
@@ -136,16 +141,21 @@ op_get_in_param (struct aop_dynval *dv)
 }
 
 /**
- * Get a dynval representing parameter n passed to a function call.
- * Note that you must use aop_filter_entry_by_in_param() to filter a
+ * Get a dynval representing the nth parameter passed to the current
+ * fuction.  Be careful not to capture the <code>in_param</code> of
+ * the current function when you actually intend to capture the
+ * <code>call_param</code> being passed to a function call join point.
+ * (For the latter, use aop_capture_param() instead).
+ *
+ * Note that you must use aop_filter_by_in_param() to filter a
  * pointcut by parameter type for any parameter you wish to capture
  * with this function.
- * \param jp A function call join point.  Function entry join points
- * are obtained by joining on an aop_match_function_entry() pointcut.
+ * \param jp Any kind of join point.  Join points are obtained by
+ * joining on a pointcut.
  * \param n The index of the parameter to capture.  Parameters are
  * indexed from zero.
  * \return A dynval with its type determined by
- * aop_filter_call_pc_by_param().
+ * aop_filter_by_in_param().
  */
 struct aop_dynval *
 aop_capture_in_param (struct aop_joinpoint *jp, int n)
@@ -219,10 +229,15 @@ check_in_params (struct aop_pointcut *pc)
 }
 
 /**
- * Filter a function entry pointcut to only include function entries
- * with a parameter that matches a specified type.  This filter removes join
- * points when parameter n does not match type or when there is no
- * parameter n.
+ * Filter a pointcut (of any type) to only include join points within
+ * functions that take an nth parameter matching the specified type.
+ * Be careful not to use this function when you actually intend to
+ * filter a function call pointcut by the parameters that the function
+ * call takes.  (For the latter, use aop_filter_call_pc_by_param()).
+ *
+ * Because pointcuts are created per function, this kind of filtering
+ * is actually all-or-nothing.  It will either empty the pointcut or
+ * leave it as is.
  *
  * Filters on the same parameter do not stack on top of each other.
  * If multiple parameter filters with the same n are applied a
@@ -230,8 +245,7 @@ check_in_params (struct aop_pointcut *pc)
  *
  * Note that you must filter a parameter by its type in order to
  * capture it with aop_capture_in_param().
- * \param pc The function call pointcut to filter.  Function entry
- * pointcuts are created with aop_match_function_entry().
+ * \param pc The pointcut to filter.
  * \param n The index of the parameter to filter on.  Parameters are
  * indexed from zero.
  * \param The parameter type to filter by.