From: Justin Seyster <jseyster@cs.sunysb.edu>
Date: Wed, 28 Jul 2010 00:51:43 +0000 (-0400)
Subject: Updated doxygen comments for aop_capture_lhs_var_scope.
X-Git-Tag: release-v1.0~78
X-Git-Url: https://git.fsl.cs.stonybrook.edu/?a=commitdiff_plain;h=758bf3be73e05177136806a10791b552a67bf290;p=interaspect.git

Updated doxygen comments for aop_capture_lhs_var_scope.
---

diff --git a/src/aop-pc-assign.c b/src/aop-pc-assign.c
index 1212d1a..710e25d 100644
--- a/src/aop-pc-assign.c
+++ b/src/aop-pc-assign.c
@@ -43,6 +43,8 @@
  * \{
  */
 
+/* Determine if an assignment join point assigns directly to a
+   variable and return that variable.  Return NULL otherwise.  */
 static tree
 get_lhs_var (struct aop_joinpoint *jp)
 {
@@ -54,10 +56,10 @@ get_lhs_var (struct aop_joinpoint *jp)
   stmt = gsi_stmt (*jp->gsi);
   aop_assert (gimple_has_lhs (stmt));
   lhs = gimple_get_lhs (stmt);
-  
+
   if (TREE_CODE (lhs) == SSA_NAME)
     lhs = SSA_NAME_VAR (lhs);
-  
+
   if (lhs != NULL)
     return lhs;
   else
@@ -155,7 +157,7 @@ op_get_lhs_addr (struct aop_dynval *dv)
   return lhs_pointer;
 }
 
-/** 
+/**
  * Get a dynval representing the address of the variable being
  * assigned to at an assignment joinpoint.
  * Note that this capture function will return NULL if the joinpoint
@@ -263,7 +265,7 @@ op_prepare_assign (struct aop_joinpoint *jp)
      real_lhs = tmp_lhs;
 
      That way, any advice inserted before the assignment will still
-     get called after the function call. 
+     get called after the function call.
 
      Even when the assignment does not have a function call, splitting
      the assignment like this makes it much easier to capture the
@@ -300,7 +302,7 @@ stmt_matches_pointcut (struct aop_pointcut *pc, gimple stmt)
 }
 
 static void
-op_join_on_assign (struct aop_pointcut *pc, join_callback cb, 
+op_join_on_assign (struct aop_pointcut *pc, join_callback cb,
 		   void *callback_param)
 {
   basic_block bb;
@@ -379,17 +381,22 @@ aop_match_assignment_by_type (const struct aop_type *type)
 }
 
 /**
- * Returns scope of the LHS variable of the assignment statement.
- * \param jp The joinpoint corresponding to the assignment statement.
- * \return The scope of the LHS variable.
+ * Return the scope of the variable that an assignment statement
+ * assigns to (i.e., the left-hand side), which will be on of the
+ * values in enum #aop_scope.  If the assignment assigns to something
+ * other than a variable, return AOP_MEMORY_SCOPE.
+ * \param jp An assignment joinpoint.  Assignment joinpoints are
+ * obtained by joining on an aop_match_assignment_by_type() pointcut.
+ * \return For a direct assignment to a variable, the scope of that
+ * variable, otherwise AOP_MEMORY_SCOPE.
  */
 enum aop_scope
 aop_capture_lhs_var_scope (struct aop_joinpoint *jp)
 {
   tree lhs;
-  lhs = get_lhs_var (jp); 
+  lhs = get_lhs_var (jp);
   if (lhs != NULL_TREE)
-    {     
+    {
       if (DECL_FILE_SCOPE_P (lhs))
 	{
 	  if (!TREE_PUBLIC (lhs))
@@ -401,9 +408,9 @@ aop_capture_lhs_var_scope (struct aop_joinpoint *jp)
 	      return AOP_GLOBAL_SCOPE;
 	    }
 	}
-      else if (TREE_CODE (DECL_CONTEXT (lhs)) == FUNCTION_DECL) 
+      else if (TREE_CODE (DECL_CONTEXT (lhs)) == FUNCTION_DECL)
 	{
-	  return AOP_FUNCTION_SCOPE;  
+	  return AOP_FUNCTION_SCOPE;
 	}
       else
 	{
@@ -413,7 +420,7 @@ aop_capture_lhs_var_scope (struct aop_joinpoint *jp)
   else
     {
       return AOP_MEMORY_SCOPE;
-    }  
+    }
 }
 
 /* Close Doxygen defgroup block. */
diff --git a/src/aop.h b/src/aop.h
index 1e3a7de..ecca714 100644
--- a/src/aop.h
+++ b/src/aop.h
@@ -263,11 +263,36 @@ extern struct aop_dynval *aop_capture_lhs_addr (struct aop_joinpoint *jp);
 extern const char *aop_capture_lhs_name (struct aop_joinpoint *jp);
 extern struct aop_dynval *aop_capture_assigned_value (struct aop_joinpoint *jp);
 
+/**
+ * \brief Scope of a variable.
+ *
+ * The function aop_capture_lhs_var_scope() returns one of these
+ * values to indicate the scope of the variable assigned in a
+ * specified assignment statement.
+ */
 enum aop_scope {
+  /**
+   * The variable is accessible by name from anywhere in the program.
+   */
   AOP_GLOBAL_SCOPE,
+
+  /**
+   * The variable is only accessible by name from the current file.
+   */
   AOP_FILE_SCOPE,
+
+  /**
+   * The variable is only accessible by name from the current function
+   * or method.
+   */
   AOP_FUNCTION_SCOPE,
+
+  /**
+   * Used for an assignment that does not assign to a variable.  For
+   * example, the assignment may be to a field in a struct or a
+   * dereferenced pointer.
+   */
   AOP_MEMORY_SCOPE,
 };
-enum aop_scope aop_capture_lhs_var_scope (struct aop_joinpoint *jp);
+extern enum aop_scope aop_capture_lhs_var_scope (struct aop_joinpoint *jp);
 #endif