Add instructionAPI/Dereference.h

docs/instructionAPI/public/Dereference.h.rst

@@ -1,71 +1,100 @@
+.. _`sec:Dereference.h`:
+
 Dereference.h
-=============
+#############
 
 .. cpp:namespace:: Dyninst::InstructionAPI
 
-Dereference Class
------------------
+.. cpp:class:: Dereference
+
+  **Expression for an effective address**
+
+  .. cpp:function:: Dereference(Expression::Ptr addr, Result_Type result_type)
+
+    Constructs an expression representing the address to be dereferenced and a type
+    indicating how the memory at the address in question is to be interpreted.
+
+  .. cpp:function:: virtual void getChildren(vector<InstructionAST::Ptr>& children) const
+
+    Appends the children of this :cpp:class:`Expression` node to ``children`` as an ``InstructionAST``.
+
+    A ``Dereference`` has one child, which represents the address being dereferenced.
+
+  .. cpp:function:: virtual void getChildren(vector<Expression::Ptr>& children) const
+
+    Appends the children of this :cpp:class:`Expression` node to ``children`` as a generic ``Expression``.
+
+    A ``Dereference`` has one child, which represents the address being dereferenced.
+
+  .. cpp:function:: virtual void getUses(set<InstructionAST::Ptr>& uses)
+
+    Appends the use set to ``uses``.
+
+    The use set of a dereference is the same as the use set of the expression being dereferenced.
+
+  .. cpp:function:: virtual bool isUsed(InstructionAST::Ptr i) const
+
+    Checks if ``i`` is in this expression's used set.
+
+    A expression is used if it is equivalent to the ``Dereference`` or it is
+    used by the child of the ``Dereference``.
+
+  .. cpp:function:: virtual std::string format(formatStyle) const
+
+    Returns a string representation of this expression using the style ``formatStyle``.
+
+  .. cpp:function:: virtual std::string format(Architecture arch, formatStyle) const
 
-A ``Dereference`` object is an ``Expression`` that dereferences another
-``ValueComputation``.
+    Returns a string representation of this expression using the :cpp:class:`ArchSpecificFormatter`
+    associated with ``arch``. ``formatStyle`` is ignored.
 
-A ``Dereference`` contains an ``Expression`` representing an effective
-address computation. Its use set is the same as the use set of the
-``Expression`` being dereferenced.
+  .. cpp:function:: virtual bool bind(Expression* expr, const Result& value)
+
+    Binds ``expr`` to ``value``.
+
+  .. cpp:function:: virtual void apply(Visitor* v)
+
+    Applies the visitor ``v``.
+
+  .. cpp:function:: protected virtual bool isSameType(const InstructionAST& rhs) const
+
+    Checks if ``rhs`` is a ``Dereference``.
+
+  .. cpp:function:: protected virtual bool isStrictEqual(const InstructionAST& rhs) const
+
+    Checks if this expression is the same as ``rhs``.
+
+
+Notes
+=====
 
 It is not possible, given the information in a single instruction, to
-evaluate the result of a dereference. ``eval`` may still be called on an
-``Expression`` that includes dereferences, but the expected use case is
+evaluate the result of a dereference. :cpp:func:`eval` may still be called on an
+expression that includes dereferences, but the expected use case is
 as follows:
 
--  Determine the address being used in a dereference via the ``eval``
-   mechanism
+1. Determine the address being used in a dereference.
 
--  Perform analysis to determine the contents of that address
+2. Perform analysis to determine the contents of that address.
 
--  If necessary, fill in the ``Dereference`` node with the contents of
-   that addresss, using ``setValue``
+3. If necessary, fill in the ``Dereference`` node with the contents of
+   that addresss, using :cpp:func:`setValue`.
 
 The type associated with a ``Dereference`` node will be the type of the
-value *read* *from* *memory*, not the type used for the address
+value *read from memory*, not the type used for the address
 computation. Two ``Dereference``\ s that access the same address but
 interpret the contents of that memory as different types will produce
 different values. The children of a ``Dereference`` at a given address
 are identical, regardless of the type of dereference being performed at
-that address. For example, the ``Expression`` shown in Figure 6 could
+that address. For example, the expression shown in the figure below could
 have its root ``Dereference``, which interprets the memory being
 dereferenced as a unsigned 16-bit integer, replaced with a
 ``Dereference`` that interprets the memory being dereferenced as any
-other type. The remainder of the ``Expression`` tree would, however,
+other type. The remainder of the expression tree would, however,
 remain unchanged.
 
-.. code-block:: cpp
-
-    Dereference (Expression::Ptr addr, Result_Type result_type)
-
-A ``Dereference`` is constructed from an ``Expression`` pointer (raw or
-shared) representing the address to be dereferenced and a type
-indicating how the memory at the address in question is to be
-interpreted.
-
-.. code-block:: cpp
-
-    virtual void getChildren (vector< InstructionAST::Ptr > & children) const
-
-A ``Dereference`` has one child, which represents the address being
-dereferenced. Appends the child of this ``Dereference`` to ``children``.
-
-.. code-block:: cpp
-
-    virtual void getUses (set< InstructionAST::Ptr > & uses)
-
-The use set of a ``Dereference`` is the same as the use set of its
-children. The use set of this ``Dereference`` is inserted into ``uses``.
-
-.. code-block:: cpp
-
-    virtual bool isUsed (InstructionAST::Ptr findMe) const
+.. figure:: ../fig/deref-eval.png
+  :name: fig:deref-eval
+  :align: center
 
-An ``InstructionAST`` is used by a ``Dereference`` if it is equivalent
-to the ``Dereference`` or it is used by the lone child of the
-``Dereference``
+  Applying eval to a Dereference tree with two registers having user-provided values.

docs/instructionAPI/public/Expression.h.rst

@@ -70,10 +70,6 @@ address is available from the Dereference through its child in the tree,
 even though calling ``eval`` on the Dereference returns a ``Result``
 with an undefined value.
 
-.. figure:: fig/deref-eval.pdf
-   :alt: Applying eval to a Dereference tree with two registers having user-provided values.
-   :name: fig:deref-eval
-
 .. code-block:: cpp
 
     typedef boost::shared_ptr<Expression> Ptr

instructionAPI/h/Dereference.h

@@ -48,41 +48,18 @@ namespace Dyninst
   {
     using std::vector;
 
-    /// A %Dereference object is a %Expression that dereferences another %ValueComputation.
-    ///
-    /// A %Dereference contains an %Expression representing an effective address computation.
-    /// Its use set is the same as the use set of the
-    /// %Expression being dereferenced.
-    ///
-    /// It is not possible, given the information in a single instruction, to evaluate
-    /// the result of a dereference.  \c eval may still be called on a %Expression
-    /// that includes dereferences, but the expected use case is as follows:
-    ///   - Determine the address being used in a dereference via the \c eval mechanism
-    ///   - Perform analysis to determine the contents of that address
-    ///   - If necessary, fill in the %Dereference node with the contents of that addresss, using \c setValue
-    ///
-    /// The type associated with a %Dereference node will be the type of the value \em read \em from \em memory,
-    /// not the type used for the address computation.  Two %Dereferences that access the same address but interpret
-    /// the contents of that memory as different types will produce different values.  The children of a %Dereference at
-    /// a given address are identical, regardless of the type of dereference being performed at that address.
-    /// For example, the %Expression shown in Figure 6 could have its root %Dereference, which interprets the memory being dereferenced
-    /// as a unsigned 16-bit integer, replaced with a %Dereference that
-    /// interprets the memory being dereferenced as any other type.  The remainder of the %Expression tree would, however, remain unchanged.
     class INSTRUCTION_EXPORT Dereference : public Expression
     {
 
     public:
-      /// A %Dereference is constructed from a %Expression pointer (raw or shared) representing the address
-      /// to be dereferenced and a type
-      /// indicating how the memory at the address in question is to be interpreted.
+
       Dereference(Expression::Ptr addr, Result_Type result_type) : Expression(result_type), addressToDereference(addr)
       {
       }
       virtual ~Dereference() 
       {
       }
-      /// A %Dereference has one child, which represents the address being dereferenced.
-      /// \param children Appends the child of this %Dereference to \c children.
+
       virtual void getChildren(vector<InstructionAST::Ptr>& children) const
       {
 	children.push_back(addressToDereference);
@@ -93,15 +70,13 @@ namespace Dyninst
           children.push_back(addressToDereference);
           return;
       }
-      /// The use set of a %Dereference is the same as the use set of its children.
-      /// \param uses The use set of this %Dereference is inserted into \c uses.
+
       virtual void getUses(set<InstructionAST::Ptr>& uses)
       {
 	addressToDereference->getUses(uses);
 	return;
       }
-        /// An %InstructionAST is used by a %Dereference if it is equivalent to the 
-        /// %Dereference or it is used by the lone child of the %Dereference
+
         virtual bool isUsed(InstructionAST::Ptr findMe) const
         {
             return addressToDereference->isUsed(findMe) || *findMe == *this;