From: Justin Seyster <jseyster@cs.sunysb.edu>
Date: Thu, 1 Jul 2010 22:27:33 +0000 (-0400)
Subject: Documented several functions.
X-Git-Tag: release-v1.0~95
X-Git-Url: https://git.fsl.cs.stonybrook.edu/?a=commitdiff_plain;h=8e583d79d8d613856803f7dccf1956b65c18bc36;p=interaspect.git

Documented several functions.
---

diff --git a/src/aop-pc-fun-call.c b/src/aop-pc-fun-call.c
index 922f3a9..e142cef 100644
--- a/src/aop-pc-fun-call.c
+++ b/src/aop-pc-fun-call.c
@@ -149,6 +149,13 @@ op_join_on_function_call (struct aop_pointcut *pc, join_callback cb,
     }
 }
 
+/**
+ * Return a pointcut that matches all function calls.  Use filter
+ * functions on the resulting pointcut to produce a pointcut that
+ * matches calls to a narrower set of functions (or a single
+ * function).
+ * \return The resulting pointcut.
+ */
 struct aop_pointcut *
 aop_match_function_call ()
 {
@@ -167,11 +174,18 @@ aop_match_function_call ()
   return pc;
 }
 
+/**
+ * Filter a function call pointcut to only include calls to functions
+ * with a specified name.
+ * \param pc The function call pointcut to filter.  Function call
+ * pointcuts are created with aop_match_function_call().
+ * \param name The name to filter by.
+ */
 void
-aop_filter_function_call_pointcut (struct aop_pointcut *pc_function_call,
-				   const char *advice_function_call)
+aop_filter_call_pc_by_name (struct aop_pointcut *pc_function_call,
+			    const char *name)
 {
-  pc_function_call->pc_call.function_name = advice_function_call;
+  pc_function_call->pc_call.function_name = name;
 }
 
 void
@@ -225,6 +239,15 @@ op_get_return_value (struct aop_dynval *dv)
   return return_value;
 }
 
+/**
+ * Filter a function call pointcut to only include calls to functions
+ * with a specified return type.  Note that you must filter a pointcut
+ * by return type in order to call aop_capture_return_value() on any
+ * of its join points.
+ * \param pc The function call pointcut to filter.  Function call
+ * pointcuts are created with aop_match_function_call().
+ * \param type The return type to filter by.
+ */
 void
 aop_filter_call_pc_by_return_type (struct aop_pointcut *pc,
 				   const struct aop_type *type)
@@ -232,6 +255,15 @@ aop_filter_call_pc_by_return_type (struct aop_pointcut *pc,
   pc->pc_call.return_type = type;
 }
 
+/**
+ * Get a dynval representing a function call's return value.  Note
+ * that you must filter with aop_filter_call_pc_by_return_type() in
+ * order to capture the return value using aop_capture_return_value().
+ * \param jp A function call join point.  Function call join points
+ * are obtained by joining on an aop_match_function_call() pointcut.
+ * \return A dynval with a type determined by
+ * aop_filter_call_pc_by_return_type().
+ */
 struct aop_dynval *
 aop_capture_return_value (struct aop_joinpoint *jp)
 {
diff --git a/src/aop.h b/src/aop.h
index 505ce54..381d635 100644
--- a/src/aop.h
+++ b/src/aop.h
@@ -101,8 +101,8 @@ extern void aop_filter_entry_by_name(struct aop_pointcut *pc_function_entry,
 
 extern struct aop_pointcut *aop_match_function_call ();
 
-extern void aop_filter_function_call_pointcut (
-  struct aop_pointcut *pc_function_call, const char *advice_function_call);
+extern void aop_filter_call_pc_by_name (struct aop_pointcut *pc_function_call,
+					const char *advice_function_call);
 extern void aop_filter_call_pc_by_return_type (struct aop_pointcut *pc,
 					       const struct aop_type *type);
 extern void aop_filter_function_call_pointcut_by_param_index (