Add common/Node.h

dyninst · Apr 3, 2024 · 90ad8cd · 90ad8cd
1 parent 310722e
commit 90ad8cd
Show file tree

Hide file tree

Showing 2 changed files with 66 additions and 47 deletions.
diff --git a/common/h/Node.h b/common/h/Node.h
@@ -186,26 +186,16 @@ class COMMON_EXPORT NodeIterator {
 
     NodeIterator &operator=(const NodeIterator &rhs);
 
-
-    // For code such as:
-    // NodeIterator begin, end;
-    // graph->entryNodes(begin, end);
     NodeIterator();
 
-    // Main constructor
-    // The iter parameter becomes owned by the iterator and will be destroyed
-    // when the iterator is destroyed.
     NodeIterator(NodeIteratorImpl *iter);
 
-    // Aaaand let's _really_ not forget the copy constructor
     NodeIterator(const NodeIterator &rhs);
 
     ~NodeIterator();
 
  protected:
 
-    // We hide the internal iteration behavior behind a pointer. 
-    // This allows us to override (yay for virtual functions).
     NodeIteratorImpl *iter_;
 
     NodeIteratorImpl *copy() const;

diff --git a/docs/common/public/Node.h.rst b/docs/common/public/Node.h.rst
@@ -7,41 +7,70 @@ Node.h
 
 .. cpp:class:: Node
 
-   .. cpp:type:: boost::shared_ptr<Node> Ptr;
-      
-      Shared pointer for Node
-
-   .. cpp:function:: void ins(EdgeIterator &begin, EdgeIterator &end)
-   .. cpp:function:: void outs(EdgeIterator &begin, EdgeIterator &end)
-      
-      Iterate over incoming/outgoing edges of this node.
-
-   .. cpp:function:: void ins(NodeIterator &begin, NodeIterator &end)
-   .. cpp:function:: void outs(NodeIterator &begin, NodeIterator &end)
-      
-      Iterate over adjacent nodes connected with incoming/outgoing edges of
-      this node.
-
-   .. cpp:function:: bool hasInEdges()
-   .. cpp:function:: bool hasOutEdges()
-      
-      Return ``true`` if this node has incoming/outgoing edges.
-
-   .. cpp:function:: void deleteInEdge(EdgeIterator e)
-   .. cpp:function:: void deleteOutEdge(EdgeIterator e)
-      
-      Delete an incoming/outgoing edge.
-
-   .. cpp:function:: virtual Address addr() const
-      
-      Return the address of this node.
-
-   .. cpp:function:: virtual std::string format() const = 0;
-      
-      Return the string representation.
-
+  **A node in a graph**
+
+  This is the node type used in :cpp:class:`Graph` to make an :cpp:class:`AST`.
+
+  .. cpp:type:: boost::shared_ptr<Node> Ptr
+
+    Shared pointer for Node.
+
+  .. cpp:function:: void ins(EdgeIterator &begin, EdgeIterator &end)
+
+    Iterates over incoming edges of this node.
+
+  .. cpp:function:: void outs(EdgeIterator &begin, EdgeIterator &end)
+
+    Iterates over outgoing edges of this node.
+
+  .. cpp:function:: void ins(NodeIterator &begin, NodeIterator &end)
+
+    Iterates over adjacent nodes connected with incoming edges of this node.
+
+  .. cpp:function:: void outs(NodeIterator &begin, NodeIterator &end)
+
+    Iterates over adjacent nodes connected with outgoing edges of this node.
+
+  .. cpp:function:: bool hasInEdges()
+
+    Checks if this node has any incoming edges.
+
+  .. cpp:function:: bool hasOutEdges()
+
+    Checks if this node has any outgoing edges.
+
+  .. cpp:function:: void deleteInEdge(EdgeIterator e)
+
+    Delete the incoming edge, ``e``.
+
+  .. cpp:function:: void deleteOutEdge(EdgeIterator e)
+
+    Delete the outgoing edge, ``e``.
+
+  .. cpp:function:: void forwardClosure(NodeIterator &begin, NodeIterator &end)
+  .. cpp:function:: void backwardClosure(NodeIterator &begin, NodeIterator &end)
+
+  .. cpp:function:: virtual Address addr() const
+
+    Returns the address of this node.
+
+  .. cpp:function:: virtual std::string format() const = 0
+
+    Returns the string representation.
+
+  .. cpp:function:: virtual Node::Ptr copy() = 0
+
+    Returns a deep copy of the current node.
+
+  .. cpp:function:: virtual bool isVirtual() const = 0
+  .. cpp:function:: virtual std::string DOTshape() const;
+  .. cpp:function:: virtual std::string DOTrank() const;
+  .. cpp:function:: virtual std::string DOTname() const;
+  .. cpp:function:: virtual bool DOTinclude() const
+
 .. cpp:class:: NodeIterator
-   
-   Iterator for nodes. Common iterator operations including ``++``, ``–``,
-   and dereferencing are supported.
-
+
+  **Iterator for nodes**
+
+  This class satisfies the requirements for
+  `LegacyForwardIterator <https://en.cppreference.com/w/cpp/named_req/ForwardIterator>`_.