From: Justin Seyster <jseyster@cs.sunysb.edu>
Date: Thu, 23 Sep 2010 22:58:16 +0000 (-0400)
Subject: Updated docs for in_params.
X-Git-Tag: release-v1.0~40^2
X-Git-Url: https://git.fsl.cs.stonybrook.edu/?a=commitdiff_plain;h=74c5f8c1e3b1c29cea02821703b459df87c36fb3;p=interaspect.git

Updated docs for in_params.
---

diff --git a/src/aop-pointcut.c b/src/aop-pointcut.c
index c4f23e1..f53c80f 100644
--- 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.