Add common/Edge.h

dyninst · Apr 3, 2024 · 4f18d3d · 4f18d3d
1 parent 5fe083f
commit 4f18d3d
Show file tree

Hide file tree

Showing 4 changed files with 50 additions and 27 deletions.
diff --git a/common/h/Edge.h b/common/h/Edge.h
@@ -112,13 +112,7 @@ class COMMON_EXPORT EdgeIterator {
 
  protected:
 
-    // Main constructor
-    // The iter parameter becomes owned by the iterator and will be destroyed
-    // when the iterator is destroyed.
 
-
-    // We hide the internal iteration behavior behind a pointer. 
-    // This allows us to override (yay for virtual functions).
     EdgeIteratorImpl *iter_;
 };
 

diff --git a/docs/common/developer/API.rst b/docs/common/developer/API.rst
@@ -28,6 +28,7 @@ Classes and features shared among many parts of Dyninst.
    dyn_register.h
    dyn_syscalls.h
    dyntypes.h
+   Edge.h
    freebsdHeaders.h
    freebsdKludges.h
    headers.h

diff --git a/docs/common/developer/Edge.h.rst b/docs/common/developer/Edge.h.rst
@@ -0,0 +1,42 @@
+.. _`sec:dev-Edge.h`:
+
+Edge.h
+######
+
+.. cpp:namespace:: Dyninst::dev
+
+.. cpp:class:: Edge
+
+  .. cpp:type:: private boost::shared_ptr<Node> NodeSharedPtr
+  .. cpp:type:: private boost::weak_ptr<Node> NodePtr
+
+  These member functions are technically all private because :cpp:type:`NodeSharedPtr` and
+  :cpp:type:`NodePtr` are private.
+
+  .. cpp:function:: static Ptr createEdge(const NodeSharedPtr source, const NodeSharedPtr target);
+
+    Create a new directed edge from ``source`` to ``target``.
+
+  .. cpp:function:: NodeSharedPtr source() const
+  .. cpp:function:: NodeSharedPtr target() const
+
+    Return the source / target Dyninst::Node.
+
+  .. cpp:function:: void setSource(NodeSharedPtr source)
+  .. cpp:function:: void setTarget(NodeSharedPtr target)
+
+.. cpp:class:: EdgeIterator
+
+  .. cpp:type:: protected EdgeIteratorImpl *iter_
+
+     We hide the internal iteration behavior behind a pointer.
+     This allows us to override.
+
+.. cpp:class:: EdgeIteratorImpl
+
+    .. cpp:function:: virtual void inc() = 0;
+    .. cpp:function:: virtual Dyninst::Edge::Ptr get() = 0;
+    .. cpp:function:: virtual bool equals(EdgeIteratorImpl *) = 0;
+    .. cpp:function:: virtual EdgeIteratorImpl *copy() = 0;
+
+.. cpp:class:: EdgeIteratorSet : public EdgeIteratorImpl
diff --git a/docs/common/public/Edge.h.rst b/docs/common/public/Edge.h.rst
@@ -7,27 +7,13 @@ Edge.h
 
 .. cpp:class:: Edge
 
-   .. cpp:type:: boost::shared_ptr<Edge> Edge::Ptr;
-      
-      Shared pointer for ``Edge``.
-
-   .. cpp:function:: static Edge::Ptr Edge::createEdge(const Node::Ptr source, const Node::Ptr target)
-      
-      Create a new directed edge from ``source`` to ``target``.
-
-   .. cpp:function:: Node::Ptr Edge::source() const
-   .. cpp:function:: Node::Ptr Edge::target() const
-      
-      Return the source / target node.
-
-   .. cpp:function:: void Edge::setSource(Node::Ptr source)
-   .. cpp:function:: void Edge::setTarget(Node::Ptr target)
-      
-      Set the source / target node.
-
-.. cpp:namespace:: EdgeIterator
+  .. cpp:type:: boost::shared_ptr<Edge> Ptr
+
+    Shared pointer for Edge.
 
 .. cpp:class:: EdgeIterator
    
-   Iterator for edges. Common iterator operations including ``++``, ``–``,
-   and dereferencing are supported.
+  **Iterator for edges**
+
+  This class satisfies the requirements for
+  `LegacyForwardIterator <https://en.cppreference.com/w/cpp/named_req/ForwardIterator>`_.