LocalUses and FlowAnalysis documentation bugs

[Chris Pickett <chris.pickett@mail.mcgill.ca>]

Hi,

I think I've found a couple more bugs in the API.  I've attached a 
patch that fixes both of them, although there might be better ways to do 
it (as was the case with FlowSet.java).

First, LocalUses says it returns a List of Units, whereas in reality 
both implementations of this interface return a List of 
UnitValueBoxPairs.  Also, SimpleLocalUses says it returns a 
UnitValueBoxPair, but it returns a List of them.

Second, at line 139 of BackwardFlowAnalysis.java:

  flowThrough(afterFlow, s, beforeFlow);

which says that the afterFlow is the IN set and the beforeFlow is the 
OUT set.

And at line 159 of ForwardFlowAnalysis.java:

  flowThrough(beforeFlow, s, afterFlow);

which says that the beforeFlow is the IN set and the afterFlow is the 
OUT set.

(okay, there are other places to see it, but that seems clearest)

However, the documentation says that getFlowBefore(s) returns the IN set 
and getFlowAfter(s) returns the OUT set, and makes no mention of 
direction.  I had assumed until now that "before" always meant "in" and 
"after" always mean "out", and only just caught this bug in my analyses. 
 If I'm wrong, then I've seriously misunderstood something here, and 
would still appreciate an explanation.

I'm not sure, but it might be worth checking through all 
BackwardFlowAnalysis subclasses and their clients to see that they 
understand before and after correctly.

Thanks,
Chris

Index: src/soot/toolkits/scalar/FlowAnalysis.java
===================================================================
--- src/soot/toolkits/scalar/FlowAnalysis.java	(revision 1518)
+++ src/soot/toolkits/scalar/FlowAnalysis.java	(working copy)
@@ -53,7 +53,9 @@
     /** Given the merge of the <code>out</code> sets, compute the <code>in</code> set for <code>s</code> (or in to out, depending on direction). */
     protected abstract void flowThrough(Object in, Object d, Object out);
 
-    /** Accessor function returning value of OUT set for s. */
+    /** Accessor function returning value of OUT set for s if s is a
+     *  ForwardFlowAnalysis, and the IN set for s if s is a
+     *  BackwardFlowAnalysis. */
     public Object getFlowAfter(Object s)
     {
         return unitToAfterFlow.get(s);
Index: src/soot/toolkits/scalar/AbstractFlowAnalysis.java
===================================================================
--- src/soot/toolkits/scalar/AbstractFlowAnalysis.java	(revision 1518)
+++ src/soot/toolkits/scalar/AbstractFlowAnalysis.java	(working copy)
@@ -96,7 +96,10 @@
      * Typically called from a concrete FlowAnalysis's constructor.*/
     protected abstract void doAnalysis();
 
-    /** Accessor function returning value of IN set for s. */
+
+    /** Accessor function returning value of IN set for s if s is a
+     *  ForwardFlowAnalysis, and the OUT set for s if s is a
+     *  BackwardFlowAnalysis. */
     public Object getFlowBefore(Object s)
     {
         return unitToBeforeFlow.get(s);
Index: src/soot/toolkits/scalar/SimpleLocalUses.java
===================================================================
--- src/soot/toolkits/scalar/SimpleLocalUses.java	(revision 1518)
+++ src/soot/toolkits/scalar/SimpleLocalUses.java	(working copy)
@@ -162,7 +162,7 @@
      *  a list of UnitValueBoxPairs each containing a Unit that use the
      *  local and the Local itself wrapped in a ValueBox.
      *  @param s a unit that we want to query for the uses of the Local it (may) define.
-     *  @return a UnitValueBoxPair of the Units that use the Local.
+     *  @return a List of UnitValueBoxPairs of the Units that use the Local.
      */
     public List getUsesOf(Unit s)
     {
Index: src/soot/toolkits/scalar/LocalUses.java
===================================================================
--- src/soot/toolkits/scalar/LocalUses.java	(revision 1518)
+++ src/soot/toolkits/scalar/LocalUses.java	(working copy)
@@ -42,25 +42,13 @@
 public interface LocalUses
 {
     /**
-     *   Returns a list of the Units that use the Local that is 
-     *   defined by a given Unit. 
-     *   
-     *   @param s  the unit we wish to query for the use of the Local
-     *             it defines.
-     *   @return  a list of the Local's uses.
-     */    
+     * Uses for a Local defined at a given Unit are returned as a list
+     * of UnitValueBoxPairs each containing a Unit that use the local
+     * and the Local itself wrapped in a ValueBox.
+     * 
+     *  @param s a unit that we want to query for the uses of the
+     *           Local it (may) define.
+     *  @return a List of UnitValueBoxPairs of the Units that use the Local.
+     */
     public List getUsesOf(Unit s);
 }
-
-
-
-
-
-
-
-
-
-
-
-
-