Add symtabAPI/Variable.h

docs/symtabAPI/developer/API.rst

@@ -32,4 +32,5 @@ SymtabAPI
   StringTable.h
   Symbol.h
   SymtabReader.h
-  Type-mem.h
+  Type-mem.h
+  Variable.h

docs/symtabAPI/developer/Variable.h.rst

@@ -0,0 +1,37 @@
+.. _`sec-dev:Variable.h`:
+
+Variable.h
+##########
+
+.. cpp:namespace:: Dyninst::SymtabAPI::dev
+
+.. cpp:class:: Variable : public Aggregate, public AnnotatableSparse
+
+  .. cpp:function:: bool removeSymbol(Symbol *sym)
+  .. cpp:function:: void setType(boost::shared_ptr<Type> type)
+  .. cpp:function:: void setType(Type* t)
+  .. cpp:function:: bool operator==(const Variable &v)
+
+
+.. cpp:class:: localVar : public AnnotatableSparse
+
+  .. cpp:member:: private bool locsExpanded_
+
+      We start with an abstract location that may include "the frame pointer" as a register.
+      Once a user requests the location list we concretize it and set this flag.
+
+  .. cpp:function:: bool addLocation(const VariableLocation &location)
+  .. cpp:function:: void fixupUnknown(Module *)
+
+  .. cpp:function:: bool setType(boost::shared_ptr<Type> newType)
+
+  .. cpp:function:: bool setType(Type *type)
+
+      Sets the type of the variable to ``type``.
+
+  .. cpp:function:: bool operator==(const localVar &l)
+
+  .. cpp:function:: localVar(std::string name,  boost::shared_ptr<Type> typ, std::string fileName, int lineNum, \
+                             FunctionBase *f, std::vector<VariableLocation> *locs = NULL)
+
+  .. cpp:function:: localVar(std::string n, Type* t, std::string fn, int l, FunctionBase *f, std::vector<VariableLocation> *ls = NULL)

docs/symtabAPI/public/Variable.h.rst

@@ -1,134 +1,57 @@
+.. _`sec:Variable.h`:
+
 Variable.h
-==========
+##########
 
 .. cpp:namespace:: Dyninst::SymtabAPI
 
-Class Variable
---------------
-
-The ``Variable`` class represents a collection of symbols that have the
-same address and represent data.
-
-.. list-table:: Variable Class
-   :widths: 30  35 35
-   :header-rows: 1
-
-   * - Method name
-     - Return type
-     - Method description
-   * - getOffset
-     - Offset
-     - Offset associated with this variable.
-   * - getSize
-     - unsigned
-     - Size of this variable encoded in the symbol table.
-   * - mangled_names_begin
-     - Aggregate::name_iter
-     - Beginning of a range of unique names of symbols pointing to this variable.
-   * - mangled_names_end
-     - Aggregate::name_iter
-     - End of a range of unique names of symbols pointing to this variable.
-   * - getType
-     - Type *
-     - Type of this variable, if known.
-   * - getModule
-     - const Module *
-     - Module this variable belongs to.
-   * - getRegion
-     - Region *
-     - Region that contains this variable.
-
-.. code-block:: cpp
-
-    bool getSymbols(vector<Symbol *> &syms) const
-
-This method returns the vector of ``Symbol``\ s that refer to the
-variable.
-
-.. code-block:: cpp
-
-    bool setModule (Module *module)
-
-This method changes the module to which the variable belongs. Returns
-``true`` if it succeeds.
+.. cpp:class:: Variable : public Aggregate, public AnnotatableSparse
 
-.. code-block:: cpp
-   
-    bool setSize (unsigned size)
+  **A collection of symbols that have the same address and represent data**
 
-This method changes the size of the variable to ``size``. Returns
-``true`` if it succeeds.
 
-.. code-block:: cpp
+  .. cpp:function:: Variable()
+  .. cpp:function:: boost::shared_ptr<Type> getType(Type::do_share_t)
 
-    bool setOffset (Offset offset)
+      Returns the type of this variable.
 
-The method changes the offset of the variable. Returns ``true`` if it
-succeeds.
+  .. cpp:function:: Type* getType()
 
-.. code-block:: cpp
+      Returns the type of this variable.
 
-    bool addMangledName(string name, bool isPrimary)
+  .. cpp:function:: std::ostream &operator<<(std::ostream &os, Variable const& v)
 
-This method adds a mangled name ``name`` to the variable. If
-``isPrimary`` is ``true`` then it becomes the default name for the
-variable. This method returns ``true`` on success and ``false`` on
-failure.
+      Writes a string representation of ``v`` into the stream ``os``.
 
-.. code-block:: cpp
 
-    bool addPrettyName(string name, bool isPrimary)
+.. cpp:class:: localVar : public AnnotatableSparse
 
-This method adds a pretty name ``name`` to the variable. If
-``isPrimary`` is ``true`` then it becomes the default name for the
-variable. This method returns ``true`` on success and ``false`` on
-failure.
+  **A local variable or parameter of a function**
 
-.. code-block:: cpp
+  .. cpp:function:: localVar()
+  .. cpp:function:: std::string &getName()
 
-    bool addTypedName(string name, bool isPrimary)
+      Returns the name of the local variable or parameter.
 
-This method adds a typed name ``name`` to the variable. If ``isPrimary``
-is ``true`` then it becomes the default name for the variable. This
-method returns ``true`` on success and ``false`` on failure.
+  .. cpp:function:: boost::shared_ptr<Type> getType(Type::do_share_t)
 
-.. code-block:: cpp
+      Returns the type of this variable.
 
-    bool setType(Type *type)
+  .. cpp:function:: Type* getType()
 
-Sets the type of the variable to ``type``.
+      Returns the type of this variable.
 
-Class localVar
---------------
+  .. cpp:function:: int  getLineNum()
 
-This represents a local variable or parameter of a function.
+      Returns the line number where the variable was declared, if known.
 
-.. list-table:: Class localVar
-   :widths: 30  35 35
-   :header-rows: 1
+  .. cpp:function:: std::string &getFileName()
 
-   * - Method name
-     - Return type
-     - Method description
-   * - getName
-     - string &
-     - Name of the local variable or parameter.
-   * - getType
-     - Type *
-     - Type associated with the variable.
-   * - getFileName
-     - string &
-     - File where the variable was declared, if known.
-   * - getLineNum
-     - int
-     - Line number where the variable was declared, if known.
+      Returns the file where the variable was declared, if known.
 
-.. code-block:: cpp
+  .. cpp:function:: std::vector<VariableLocation> &getLocationLists()
 
-    vector<VariableLocation> &getLocationLists()
+      Returns the locations where this variable is referenced.
 
-A local variable can be in scope at different positions and based on
-that it is accessible in different ways. Location lists provide a way to
-encode that information. The method retrieves the location list,
-specified in terms of ``VariableLocation`` structures (section
-`6.13 <#VariableLocation>`__) where the variable is in scope.
+      A local variable can be in scope at different positions and based on that it is accessible
+      in different ways. Location lists provide a way to encode that information.

symtabAPI/h/Variable.h

@@ -59,7 +59,7 @@ class SYMTAB_EXPORT Variable : public Aggregate, public AnnotatableSparse {
 
  public:
    Variable();
-    /* Symbol management */
+
     bool removeSymbol(Symbol *sym);      
 
    void setType(boost::shared_ptr<Type> type);
@@ -91,9 +91,7 @@ class SYMTAB_EXPORT localVar : public AnnotatableSparse
 	int lineNum_;
         FunctionBase *func_;
 	std::vector<VariableLocation> locs_;
-        // We start with an abstract location that may include "the frame
-        // pointer" as a register. Once a user requests the location list
-        // we concretize it and set this flag.
+
         bool locsExpanded_;
 
 	// scope_t scope;
@@ -104,22 +102,22 @@ class SYMTAB_EXPORT localVar : public AnnotatableSparse
 	public:
 	localVar() :
         type_(NULL), lineNum_(-1), func_(NULL), locsExpanded_(false) {}
-	//  Internal use only
+
 	localVar(std::string name,  boost::shared_ptr<Type> typ, std::string fileName, 
             int lineNum, FunctionBase *f, 
             std::vector<VariableLocation> *locs = NULL);
 	localVar(std::string n, Type* t, std::string fn, int l, FunctionBase *f, 
             std::vector<VariableLocation> *ls = NULL)
       : localVar(n, t->reshare(), fn, l, f, ls) {}
 
-	// Copy constructor
 	localVar(localVar &lvar);
+
 	bool addLocation(const VariableLocation &location);
 	~localVar();
 	void fixupUnknown(Module *);
 
 	public:
-	//  end of functions for internal use only
+
 	std::string &getName();
 	boost::shared_ptr<Type> getType(Type::do_share_t);
     Type* getType() { return getType(Type::share).get(); }