Updated comments to explain the new aop_capture_lhs_name() semantics.

diff --git a/src/aop-pc-assign.c b/src/aop-pc-assign.c
index 66bcf71aeb11d2eef54e1693c5b96bd2775b0e7d..07b88b8b31ce4610eb087c20bfe2fef84bfb950e 100644 (file)
--- a/src/aop-pc-assign.c
+++ b/src/aop-pc-assign.c
@@ -407,13 +407,27 @@ find_lexical_block (tree lhs, tree block, int *indexp)
 
 /**
  * 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.
+ * assigns to (i.e., the left-hand side), which will be an integer
+ * index or one of several \ref scope_val "special values".
+ *
+ * If the assignment is to a global or file-local variable, the return
+ * value will simply be #AOP_GLOBAL_SCOPE or #AOP_FILE_SCOPE,
+ * respectively.  The return value for a function-local variable is a
+ * non-negative index that corresponds to a lexical block in the
+ * function.  A single function may have multiple variables with the
+ * same name, but those variables will have a different block index.
+ *
+ * Note that you can use the AOP_LOCAL_SCOPE() macro to check if a
+ * return value indicates function-local scope.
+ *
+ * If the assignment assigns to something other than a variable, such
+ * as a field in a struct or a dereferenced pointer, the return value
+ * will be #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.
+ * variable (as a non-negative index or a \ref scope_val
+ * "special value"), otherwise #AOP_MEMORY_SCOPE.
  */
 int
 aop_capture_lhs_var_scope (struct aop_joinpoint *jp)

diff --git a/src/aop.h b/src/aop.h
index c90f7371a35275fdeafedfa8808c72e68ed893de..9e9b607dbf86e012fb43533ebaa72a1099dd141e 100644 (file)
--- a/src/aop.h
+++ b/src/aop.h
@@ -264,28 +264,39 @@ 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.
+ * \defgroup scope_val aop_capture_lhs_var_scope() Return Values
  *
- * 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.
+ * The aop_capture_lhs_var_scope() returns one of these values when
+ * the variable assigned to does not have function local scope (or
+ * when the assignment does not assign directly to a variable).
+ * \{
  */
 /**
  * The variable is accessible by name from anywhere in the program.
  */
 #define AOP_GLOBAL_SCOPE -1
-  
+
 /**
  * The variable is only accessible by name from the current file.
  */
-#define AOP_FILE_SCOPE  -2
+#define AOP_FILE_SCOPE -2
 
 /**
  * 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.
  */
-#define AOP_MEMORY_SCOPE  -3
+#define AOP_MEMORY_SCOPE -3
+
+/**
+ * Use this macro to check if a variable has function-local scope.
+ */
+#define AOP_LOCAL_SCOPE(SCOPE) (SCOPE >= 0)
+
+/* Close Doxygen defgroup block. */
+/**
+ * \}
+ */
 
 extern int aop_capture_lhs_var_scope (struct aop_joinpoint *jp);
 #endif