Add stackwalk/symlookup.h

docs/stackwalk/public/symlookup.h.rst

@@ -1,58 +1,55 @@
+.. _`sec:symlookup.h`:
+
 symlookup.h
-===========
+###########
+
+.. cpp:namespace:: Dyninst::Stackwalker
 
-.. cpp:namespace:: Dyninst::stackwalk
+.. cpp:class:: SymbolLookup
 
-Class SymbolLookup
-~~~~~~~~~~~~~~~~~~
+  **An abstract interface for associating a symbolic name with a stack frame**
 
-**Defined in:** ``symlookup.h``
+  Each frame contains a return address pointing into the function (or function-like object)
+  that created its stack frame. However, users do not always want to deal
+  with addresses when symbolic names are more convenient. This class can also associate an opaque
+  object with a frame.
 
-The ``SymbolLookup`` virtual class is an interface for associating a
-symbolic name with a stack frame. Each ``Frame`` object contains an
-address (the RA) pointing into the function (or function-like object)
-that created its stack frame. However, users do not always want to deal
-with addresses when symbolic names are more convenient. This class is an
-interface for mapping a ``Frame`` object’s RA into a name.
+  .. cpp:member:: protected Walker *walker
 
-In addition to getting a name, this class can also associate an opaque
-object (via a ``void*``) with a Frame object. It is up to the
-``SymbolLookup`` implementation what to return in this opaque object.
+  .. cpp:function:: SymbolLookup(std::string exec_path = "")
 
-The default implementation of ``SymbolLookup`` provided by
-StackwalkerAPI uses the ``SymLite`` tool to lookup symbol names. It
-returns a Symbol object in the anonymous ``void*``.
+      Constructor for a ``SymbolLookup`` object.
 
-.. code-block:: cpp
+  .. cpp:function:: virtual ~SymbolLookup()
 
-    SymbolLookup(std::string exec_path = "");
+  .. cpp:function:: virtual bool lookupAtAddr(Dyninst::Address addr, std::string &out_name, \
+                                              void* &out_value) = 0
 
-Constructor for a ``SymbolLookup`` object.
+      Returns in ``out_name`` the name of the function and the opaque data in ``out_value`` located
+      at the address ``addr``. 
+
+      ``out_value`` can be any opaque value determined by ``SymbolLookup``. The
+      values returned are used by :cpp:func:`Frame::getName` and :cpp:func:`Frame::getObject`.
 
-.. code-block:: cpp
+      This method returns ``true`` on success and ``false`` on error.
 
-    virtual bool lookupAtAddr(Address addr, string &out_name, void* &out_value) = 0
+  .. cpp:function:: virtual Walker *getWalker()
 
-This method takes an address, ``addr``, as input and returns the
-function name, ``out_name``, and an opaque value, ``out_value``, at that
-address. Output parameter ``out_name`` should be the name of the
-function that contains ``addr``. Output parameter ``out_value`` can be
-any opaque value determined by the ``SymbolLookup`` implementation. The
-values returned are used by the ``Frame::getName`` and
-``Frame::getObject`` functions.
+      Returns the associated walker.
 
-This method returns ``true`` on success and ``false`` on error.
+  .. cpp:function:: virtual ProcessState *getProcessState()
 
-.. code-block:: cpp
+      Returns the associated process state.
 
-    virtual Walker *getWalker()
+.. cpp:class:: SwkSymtab : public SymbolLookup
 
-This method returns the ``Walker`` object associated with this
-``SymbolLookup``.
+  .. cpp:function:: SwkSymtab(std::string exec_name)
+  .. cpp:function:: virtual bool lookupAtAddr(Dyninst::Address addr, std::string &out_name, void* &out_value)
+  .. cpp:function:: virtual ~SwkSymtab()
 
-.. code-block:: cpp
 
-    virtual ProcessState *getProcessSate()
+.. cpp:class:: SymDefaultLookup : public SymbolLookup
 
-This method returns the ``ProcessState`` object associated with this
-``SymbolLookup``.
+  .. cpp:function:: SymDefaultLookup(std::string exec_name)
+  .. cpp:function:: virtual bool lookupAtAddr(Dyninst::Address addr, std::string &out_name, void* &out_value)
+  .. cpp:function:: virtual ~SymDefaultLookup()