Add dyninstAPI/BPatch_loopTreeNode.h

docs/dyninstAPI/developer/API.rst

@@ -24,6 +24,7 @@ DyninstAPI
   BPatch_image.h
   BPatch_instruction.h
   BPatch_libInfo.h
+  BPatch_loopTreeNode.h
   BPatch_memoryAccessAdapter.h
   BPatch_private.h
   codegen-aarch64.h

docs/dyninstAPI/developer/BPatch_loopTreeNode.h.rst

@@ -0,0 +1,17 @@
+.. _`sec-dev:BPatch_loopTreeNode.h`:
+
+BPatch_loopTreeNode.h
+#####################
+
+.. cpp:namespace:: dev
+
+.. cpp:class:: BPatch_loopTreeNode
+
+  .. cpp:var:: private char *hierarchicalName
+
+  name which indicates this loop's relative nesting
+
+  .. cpp:var:: private BPatch_Vector<func_instance *> callees
+
+  A vector of functions called within the body of this loop (and
+  not the body of sub loops).

docs/dyninstAPI/public/BPatch_loopTreeNode.h.rst

@@ -5,75 +5,74 @@ BPatch_loopTreeNode.h
 
 .. cpp:class:: BPatch_loopTreeNode
    
-  The **BPatch_loopTreeNode** class provides a tree interface to a
-  collection of instances of class BPatch_basicBlockLoop contained in a
-  BPatch_flowGraph. The structure of the tree follows the nesting
-  relationship of the loops in a function’s flow graph. Each
-  BPatch_­loopTreeNode contains a pointer to a loop (represented by
-  BPatch_basicBlockLoop), and a set of sub-loops (represented by other
-  BPatch_loopTreeNode objects). The root BPatch_­loopTreeNode instance has
-  a null loop member since a function may contain multiple outer loops.
-  The outer loops are contained in the root instance’s vector of children.
-
-  Each instance of BPatch_loopTreeNode is given a name that indicates its
-  position in the hierarchy of loops. The name of each root loop takes the
-  form of loop_x, where x is an integer from 1 to n, where n is the number
-  of outer loops in the function. Each sub-loop has the name of its
-  parent, followed by a .y, where y is 1 to m, where m is the number of
-  sub-loops under the outer loop. For example, consider the following C
-  function:
-
-  .. code-block:: cpp
-
-    void foo() {
-       int x, y, z, i;
-
-       for (x=0; x<10; x++) {
-          for (y = 0; y<10; y++)
-          ...
-          for (z = 0; z<10; z++)
-          ...
-       }
-       for (i = 0; i<10; i++) {
-       ...
-       }
-    }
-
-  The foo function will have a root BPatch_loopTreeNode, containing a NULL
-  loop entry and two BPatch_loopTreeNode children representing the
-  functions outer loops. These children would have names loop_1 and
-  loop_2, respectively representing the x and i loops. loop_2 has no
-  children. loop_1 has two child BPatch_loopTreeNode objects, named
-  loop_1.1 and loop_1.2, respectively representing the y and z loops.
+  **A tree interface to a collection of basic blocks a CFG**
+
+  The structure of the tree follows the nesting relationship of the loops in a function’s flow graph. Each
+  ``BPatch_­loopTreeNode`` contains a pointer to a loop (represented by ``BPatch_basicBlockLoop``), and a
+  set of sub-loops (represented by other ``BPatch_loopTreeNode`` objects). The root ``BPatch_­loopTreeNode``
+  instance has a null loop member since a function may contain multiple outer loops. The outer loops are
+  contained in the root instance’s vector of children.
 
   .. cpp:var:: BPatch_basicBlockLoop *loop
 
-  A node in the tree that represents a single BPatch_basicBlockLoop
-  instance.
+  A node in the tree that represents a single BPatch_basicBlockLoop instance.
 
-  .. cpp:var:: std::vector<BPatch_loopTreeNode *> children
+  .. cpp:var:: std::vector<BPatch_loopTreeNode*> children
 
   The tree nodes for the loops nested under this loop.
 
-  .. cpp:function:: const char *name()
-
-    Return a name for this loop that indicates its position in the hierarchy
-    of loops.
+  .. cpp:function:: const char* name()
 
-  .. cpp:function:: bool getCallees(std::vector<BPatch_function *> &v, BPatch_addressSpace*p)
-
-    This function fills the vector v with the list of functions that are
-    called by this loop.
+    Return a name for this loop that indicates its position in the hierarchy of loops.
 
   .. cpp:function:: const char *getCalleeName(unsigned int i)
 
-    This function return the name of the i\ :sup:`th` function called in the
-    loop’s body.
+    This function return the name of the ``ith`` function called in the loop’s body.
 
   .. cpp:function:: unsigned int numCallees()
 
     Returns the number of callees contained in this loop’s body.
 
+  .. cpp:function:: bool getCallees(std::vector<BPatch_function*>& v, BPatch_addressSpace* p)
+
+    This function fills the vector v with the list of functions that are called by this loop.
+
   .. cpp:function:: BPatch_basicBlockLoop *findLoop(const char *name)
 
     Finds the loop object for the given canonical loop name.
+
+
+
+Notes
+*****
+
+Each instance of BPatch_loopTreeNode is given a name that indicates its
+position in the hierarchy of loops. The name of each root loop takes the
+form of loop_x, where x is an integer from 1 to n, where n is the number
+of outer loops in the function. Each sub-loop has the name of its
+parent, followed by a .y, where y is 1 to m, where m is the number of
+sub-loops under the outer loop. For example, consider the following C
+function:
+
+.. code-block:: cpp
+
+  void foo() {
+     int x, y, z, i;
+
+     for (x=0; x<10; x++) {
+        for (y = 0; y<10; y++)
+        ...
+        for (z = 0; z<10; z++)
+        ...
+     }
+     for (i = 0; i<10; i++) {
+     ...
+     }
+  }
+
+The foo function will have a root BPatch_loopTreeNode, containing a NULL
+loop entry and two BPatch_loopTreeNode children representing the
+functions outer loops. These children would have names loop_1 and
+loop_2, respectively representing the x and i loops. loop_2 has no
+children. loop_1 has two child BPatch_loopTreeNode objects, named
+loop_1.1 and loop_1.2, respectively representing the y and z loops.

dyninstAPI/h/BPatch_loopTreeNode.h

@@ -50,59 +50,34 @@ class PatchLoopTreeNode;
 }
 }
 
-/** A class to represent the tree of nested loops and 
- *  callees (functions) in the control flow graph.
- *  @see BPatch_basicBlockLoop
- *  @see BPatch_flowGraph
- */
-
 class BPATCH_DLL_EXPORT BPatch_loopTreeNode {
     friend class BPatch_flowGraph;
 
  public:
-    // A loop node contains a single BPatch_basicBlockLoop instance
     BPatch_basicBlockLoop *loop;
 
-    // The BPatch_loopTreeNode instances nested within this loop.
     BPatch_Vector<BPatch_loopTreeNode *> children;
 
-    //  BPatch_loopTreeNode::BPatch_loopTreeNode
-    //  Create a loop tree node for BPatch_basicBlockLoop with name n 
     BPatch_loopTreeNode(BPatch_flowGraph*, 
                         Dyninst::PatchAPI::PatchLoopTreeNode*, 
 			std::map<Dyninst::PatchAPI::PatchLoop*, BPatch_basicBlockLoop*>&);
 
-    //  BPatch_loopTreeNode::~BPatch_loopTreeNode
-    //  Destructor
     ~BPatch_loopTreeNode();
 
-    //  BPatch_loopTreeNode::name
-    //  Return the name of this loop. 
     const char * name(); 
 
-    //  BPatch_loopTreeNode::getCalleeName
-    //  Return the function name of the ith callee. 
     std::string getCalleeName(unsigned int i);
 
-    //  BPatch_loopTreeNode::numCallees
-    //  Return the number of callees contained in this loop's body. 
     unsigned int numCallees();
 
-    //Returns a vector of the functions called by this loop.
     bool getCallees(BPatch_Vector<BPatch_function *> &v, BPatch_addressSpace *p);
 
-
-    //  BPatch_loopTreeNode::findLoop
-    //  find loop by hierarchical name
     BPatch_basicBlockLoop * findLoop(const char *name);
 
  private:
 
-    /** name which indicates this loop's relative nesting */
     char *hierarchicalName;
 
-    // A vector of functions called within the body of this loop (and
-    // not the body of sub loops). 
     BPatch_Vector<func_instance *> callees;
 
 };