make an advanced topics section, move symtab to it

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@21473 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 241 insertions, 221 deletions

diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html
index eb3bde98a8..78ec271634 100644
--- a/docs/ProgrammersManual.html
+++ b/docs/ProgrammersManual.html
@@ -82,6 +82,12 @@ with another <tt>Value</tt></a> </li>
 --> 
     </ul>
   </li>
+
+  <li><a href="#advanced">Advanced Topics</a>
+  <ul>
+  <li><a href="#SymbolTable">The <tt>SymbolTable</tt> class </a></li>
+  </ul></li>
+
   <li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a>
     <ul>
       <li><a href="#Value">The <tt>Value</tt> class</a>
@@ -113,13 +119,6 @@ with another <tt>Value</tt></a> </li>
       </li>
     </ul>
   </li>
-  <li><a href="#SymbolTable">The <tt>SymbolTable</tt> class </a></li>
-  <li>The <tt>ilist</tt> and <tt>iplist</tt> classes
-    <ul>
-      <li>Creating, inserting, moving and deleting from LLVM lists </li>
-    </ul>
-  </li>
-  <li>Important iterator invalidation semantics to be aware of.</li>
 </ol>
 
 <div class="doc_author">    
@@ -926,6 +925,241 @@ ReplaceInstWithValue, ReplaceInstWithInst -->
 
 <!-- *********************************************************************** -->
 <div class="doc_section">
+  <a name="advanced">Advanced Topics</a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+
+</div>
+
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="SymbolTable">The <tt>SymbolTable</tt> class</a>
+</div>
+<div class="doc_text">
+<p>This class provides a symbol table that the <a
+href="#Function"><tt>Function</tt></a> and <a href="#Module">
+<tt>Module</tt></a> classes use for naming definitions. The symbol table can
+provide a name for any <a href="#Value"><tt>Value</tt></a> or <a
+href="#Type"><tt>Type</tt></a>.  <tt>SymbolTable</tt> is an abstract data
+type. It hides the data it contains and provides access to it through a
+controlled interface.</p>
+
+<p>Note that the symbol table class is should not be directly accessed by most
+clients.  It should only be used when iteration over the symbol table names
+themselves are required, which is very special purpose.  Note that not all LLVM
+<a href="#Value">Value</a>s have names, and those without names (i.e. they have
+an empty name) do not exist in the symbol table.
+</p>
+
+<p>To use the <tt>SymbolTable</tt> well, you need to understand the 
+structure of the information it holds. The class contains two 
+<tt>std::map</tt> objects. The first, <tt>pmap</tt>, is a map of 
+<tt>Type*</tt> to maps of name (<tt>std::string</tt>) to <tt>Value*</tt>. 
+The second, <tt>tmap</tt>, is a map of names to <tt>Type*</tt>. Thus, Values
+are stored in two-dimensions and accessed by <tt>Type</tt> and name. Types,
+however, are stored in a single dimension and accessed only by name.</p>
+
+<p>The interface of this class provides three basic types of operations:
+<ol>
+  <li><em>Accessors</em>. Accessors provide read-only access to information
+  such as finding a value for a name with the 
+  <a href="#SymbolTable_lookup">lookup</a> method.</li> 
+  <li><em>Mutators</em>. Mutators allow the user to add information to the
+  <tt>SymbolTable</tt> with methods like 
+  <a href="#SymbolTable_insert"><tt>insert</tt></a>.</li>
+  <li><em>Iterators</em>. Iterators allow the user to traverse the content
+  of the symbol table in well defined ways, such as the method
+  <a href="#SymbolTable_type_begin"><tt>type_begin</tt></a>.</li>
+</ol>
+
+<h3>Accessors</h3>
+<dl>
+  <dt><tt>Value* lookup(const Type* Ty, const std::string&amp; name) const</tt>:
+  </dt>
+  <dd>The <tt>lookup</tt> method searches the type plane given by the
+  <tt>Ty</tt> parameter for a <tt>Value</tt> with the provided <tt>name</tt>.
+  If a suitable <tt>Value</tt> is not found, null is returned.</dd>
+
+  <dt><tt>Type* lookupType( const std::string&amp; name) const</tt>:</dt>
+  <dd>The <tt>lookupType</tt> method searches through the types for a
+  <tt>Type</tt> with the provided <tt>name</tt>. If a suitable <tt>Type</tt>
+  is not found, null is returned.</dd>
+
+  <dt><tt>bool hasTypes() const</tt>:</dt>
+  <dd>This function returns true if an entry has been made into the type
+  map.</dd>
+
+  <dt><tt>bool isEmpty() const</tt>:</dt>
+  <dd>This function returns true if both the value and types maps are
+  empty</dd>
+</dl>
+
+<h3>Mutators</h3>
+<dl>
+  <dt><tt>void insert(Value *Val)</tt>:</dt>
+  <dd>This method adds the provided value to the symbol table.  The Value must
+  have both a name and a type which are extracted and used to place the value
+  in the correct type plane under the value's name.</dd>
+
+  <dt><tt>void insert(const std::string&amp; Name, Value *Val)</tt>:</dt>
+  <dd> Inserts a constant or type into the symbol table with the specified
+  name. There can be a many to one mapping between names and constants
+  or types.</dd>
+
+  <dt><tt>void insert(const std::string&amp; Name, Type *Typ)</tt>:</dt>
+  <dd> Inserts a type into the symbol table with the specified name. There
+  can be a many-to-one mapping between names and types. This method
+  allows a type with an existing entry in the symbol table to get
+  a new name.</dd>
+
+  <dt><tt>void remove(Value* Val)</tt>:</dt>
+ <dd> This method removes a named value from the symbol table. The
+  type and name of the Value are extracted from \p N and used to
+  lookup the Value in the correct type plane. If the Value is
+  not in the symbol table, this method silently ignores the
+  request.</dd>
+
+  <dt><tt>void remove(Type* Typ)</tt>:</dt>
+  <dd> This method removes a named type from the symbol table. The
+  name of the type is extracted from \P T and used to look up
+  the Type in the type map. If the Type is not in the symbol
+  table, this method silently ignores the request.</dd>
+
+  <dt><tt>Value* remove(const std::string&amp; Name, Value *Val)</tt>:</dt>
+  <dd> Remove a constant or type with the specified name from the 
+  symbol table.</dd>
+
+  <dt><tt>Type* remove(const std::string&amp; Name, Type* T)</tt>:</dt>
+  <dd> Remove a type with the specified name from the symbol table.
+  Returns the removed Type.</dd>
+
+  <dt><tt>Value *value_remove(const value_iterator&amp; It)</tt>:</dt>
+  <dd> Removes a specific value from the symbol table. 
+  Returns the removed value.</dd>
+
+  <dt><tt>bool strip()</tt>:</dt>
+  <dd> This method will strip the symbol table of its names leaving
+  the type and values. </dd>
+
+  <dt><tt>void clear()</tt>:</dt>
+  <dd>Empty the symbol table completely.</dd>
+</dl>
+
+<h3>Iteration</h3>
+<p>The following functions describe three types of iterators you can obtain
+the beginning or end of the sequence for both const and non-const. It is
+important to keep track of the different kinds of iterators. There are
+three idioms worth pointing out:</p>
+<table>
+  <tr><th>Units</th><th>Iterator</th><th>Idiom</th></tr>
+  <tr>
+    <td align="left">Planes Of name/Value maps</td><td>PI</td>
+    <td align="left"><pre><tt>
+for (SymbolTable::plane_const_iterator PI = ST.plane_begin(),
+     PE = ST.plane_end(); PI != PE; ++PI ) {
+  PI-&gt;first // This is the Type* of the plane
+  PI-&gt;second // This is the SymbolTable::ValueMap of name/Value pairs
+    </tt></pre></td>
+  </tr>
+  <tr>
+    <td align="left">All name/Type Pairs</td><td>TI</td>
+    <td align="left"><pre><tt>
+for (SymbolTable::type_const_iterator TI = ST.type_begin(),
+     TE = ST.type_end(); TI != TE; ++TI )
+  TI-&gt;first  // This is the name of the type
+  TI-&gt;second // This is the Type* value associated with the name
+    </tt></pre></td>
+  </tr>
+  <tr>
+    <td align="left">name/Value pairs in a plane</td><td>VI</td>
+    <td align="left"><pre><tt>
+for (SymbolTable::value_const_iterator VI = ST.value_begin(SomeType),
+     VE = ST.value_end(SomeType); VI != VE; ++VI )
+  VI-&gt;first  // This is the name of the Value
+  VI-&gt;second // This is the Value* value associated with the name
+    </tt></pre></td>
+  </tr>
+</table>
+
+<p>Using the recommended iterator names and idioms will help you avoid
+making mistakes. Of particular note, make sure that whenever you use
+value_begin(SomeType) that you always compare the resulting iterator
+with value_end(SomeType) not value_end(SomeOtherType) or else you 
+will loop infinitely.</p>
+
+<dl>
+
+  <dt><tt>plane_iterator plane_begin()</tt>:</dt>
+  <dd>Get an iterator that starts at the beginning of the type planes.
+  The iterator will iterate over the Type/ValueMap pairs in the
+  type planes. </dd>
+
+  <dt><tt>plane_const_iterator plane_begin() const</tt>:</dt>
+  <dd>Get a const_iterator that starts at the beginning of the type 
+  planes.  The iterator will iterate over the Type/ValueMap pairs 
+  in the type planes. </dd>
+
+  <dt><tt>plane_iterator plane_end()</tt>:</dt>
+  <dd>Get an iterator at the end of the type planes. This serves as
+  the marker for end of iteration over the type planes.</dd>
+
+  <dt><tt>plane_const_iterator plane_end() const</tt>:</dt>
+  <dd>Get a const_iterator at the end of the type planes. This serves as
+  the marker for end of iteration over the type planes.</dd>
+
+  <dt><tt>value_iterator value_begin(const Type *Typ)</tt>:</dt>
+  <dd>Get an iterator that starts at the beginning of a type plane.
+  The iterator will iterate over the name/value pairs in the type plane.
+  Note: The type plane must already exist before using this.</dd>
+
+  <dt><tt>value_const_iterator value_begin(const Type *Typ) const</tt>:</dt>
+  <dd>Get a const_iterator that starts at the beginning of a type plane.
+  The iterator will iterate over the name/value pairs in the type plane.
+  Note: The type plane must already exist before using this.</dd>
+
+  <dt><tt>value_iterator value_end(const Type *Typ)</tt>:</dt>
+  <dd>Get an iterator to the end of a type plane. This serves as the marker
+  for end of iteration of the type plane.
+  Note: The type plane must already exist before using this.</dd>
+
+  <dt><tt>value_const_iterator value_end(const Type *Typ) const</tt>:</dt>
+  <dd>Get a const_iterator to the end of a type plane. This serves as the
+  marker for end of iteration of the type plane.
+  Note: the type plane must already exist before using this.</dd>
+
+  <dt><tt>type_iterator type_begin()</tt>:</dt>
+  <dd>Get an iterator to the start of the name/Type map.</dd>
+
+  <dt><tt>type_const_iterator type_begin() cons</tt>:</dt>
+  <dd> Get a const_iterator to the start of the name/Type map.</dd>
+
+  <dt><tt>type_iterator type_end()</tt>:</dt>
+  <dd>Get an iterator to the end of the name/Type map. This serves as the
+  marker for end of iteration of the types.</dd>
+
+  <dt><tt>type_const_iterator type_end() const</tt>:</dt>
+  <dd>Get a const-iterator to the end of the name/Type map. This serves 
+  as the marker for end of iteration of the types.</dd>
+
+  <dt><tt>plane_const_iterator find(const Type* Typ ) const</tt>:</dt>
+  <dd>This method returns a plane_const_iterator for iteration over
+  the type planes starting at a specific plane, given by \p Ty.</dd>
+
+  <dt><tt>plane_iterator find( const Type* Typ </tt>:</dt>
+  <dd>This method returns a plane_iterator for iteration over the
+  type planes starting at a specific plane, given by \p Ty.</dd>
+
+</dl>
+</div>
+
+
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
   <a name="coreclasses">The Core LLVM Class Hierarchy Reference </a>
 </div>
 <!-- *********************************************************************** -->
@@ -1816,220 +2050,6 @@ arguments. An argument has a pointer to the parent Function.</p>
 
 </div>
 
-<!-- ======================================================================= -->
-<div class="doc_subsection">
-  <a name="SymbolTable">The <tt>SymbolTable</tt> class</a>
-</div>
-<div class="doc_text">
-<p>This class provides a symbol table that the
-<a href="#Function"><tt>Function</tt></a> and <a href="#Module">
-<tt>Module</tt></a> classes use for naming definitions. The symbol table can 
-provide a name for any <a href="#Value"><tt>Value</tt></a> or 
-<a href="#Type"><tt>Type</tt></a>.  <tt>SymbolTable</tt> is an abstract data 
-type. It hides the data it contains and provides access to it through a 
-controlled interface.</p>
-
-<p>To use the <tt>SymbolTable</tt> well, you need to understand the 
-structure of the information it holds. The class contains two 
-<tt>std::map</tt> objects. The first, <tt>pmap</tt>, is a map of 
-<tt>Type*</tt> to maps of name (<tt>std::string</tt>) to <tt>Value*</tt>. 
-The second, <tt>tmap</tt>, is a map of names to <tt>Type*</tt>. Thus, Values
-are stored in two-dimensions and accessed by <tt>Type</tt> and name. Types,
-however, are stored in a single dimension and accessed only by name.</p>
-
-<p>The interface of this class provides three basic types of operations:
-<ol>
-  <li><em>Accessors</em>. Accessors provide read-only access to information
-  such as finding a value for a name with the 
-  <a href="#SymbolTable_lookup">lookup</a> method.</li> 
-  <li><em>Mutators</em>. Mutators allow the user to add information to the
-  <tt>SymbolTable</tt> with methods like 
-  <a href="#SymbolTable_insert"><tt>insert</tt></a>.</li>
-  <li><em>Iterators</em>. Iterators allow the user to traverse the content
-  of the symbol table in well defined ways, such as the method
-  <a href="#SymbolTable_type_begin"><tt>type_begin</tt></a>.</li>
-</ol>
-
-<h3>Accessors</h3>
-<dl>
-  <dt><tt>Value* lookup(const Type* Ty, const std::string&amp; name) const</tt>:
-  </dt>
-  <dd>The <tt>lookup</tt> method searches the type plane given by the
-  <tt>Ty</tt> parameter for a <tt>Value</tt> with the provided <tt>name</tt>.
-  If a suitable <tt>Value</tt> is not found, null is returned.</dd>
-
-  <dt><tt>Type* lookupType( const std::string&amp; name) const</tt>:</dt>
-  <dd>The <tt>lookupType</tt> method searches through the types for a
-  <tt>Type</tt> with the provided <tt>name</tt>. If a suitable <tt>Type</tt>
-  is not found, null is returned.</dd>
-
-  <dt><tt>bool hasTypes() const</tt>:</dt>
-  <dd>This function returns true if an entry has been made into the type
-  map.</dd>
-
-  <dt><tt>bool isEmpty() const</tt>:</dt>
-  <dd>This function returns true if both the value and types maps are
-  empty</dd>
-</dl>
-
-<h3>Mutators</h3>
-<dl>
-  <dt><tt>void insert(Value *Val)</tt>:</dt>
-  <dd>This method adds the provided value to the symbol table.  The Value must
-  have both a name and a type which are extracted and used to place the value
-  in the correct type plane under the value's name.</dd>
-
-  <dt><tt>void insert(const std::string&amp; Name, Value *Val)</tt>:</dt>
-  <dd> Inserts a constant or type into the symbol table with the specified
-  name. There can be a many to one mapping between names and constants
-  or types.</dd>
-
-  <dt><tt>void insert(const std::string&amp; Name, Type *Typ)</tt>:</dt>
-  <dd> Inserts a type into the symbol table with the specified name. There
-  can be a many-to-one mapping between names and types. This method
-  allows a type with an existing entry in the symbol table to get
-  a new name.</dd>
-
-  <dt><tt>void remove(Value* Val)</tt>:</dt>
- <dd> This method removes a named value from the symbol table. The
-  type and name of the Value are extracted from \p N and used to
-  lookup the Value in the correct type plane. If the Value is
-  not in the symbol table, this method silently ignores the
-  request.</dd>
-
-  <dt><tt>void remove(Type* Typ)</tt>:</dt>
-  <dd> This method removes a named type from the symbol table. The
-  name of the type is extracted from \P T and used to look up
-  the Type in the type map. If the Type is not in the symbol
-  table, this method silently ignores the request.</dd>
-
-  <dt><tt>Value* remove(const std::string&amp; Name, Value *Val)</tt>:</dt>
-  <dd> Remove a constant or type with the specified name from the 
-  symbol table.</dd>
-
-  <dt><tt>Type* remove(const std::string&amp; Name, Type* T)</tt>:</dt>
-  <dd> Remove a type with the specified name from the symbol table.
-  Returns the removed Type.</dd>
-
-  <dt><tt>Value *value_remove(const value_iterator&amp; It)</tt>:</dt>
-  <dd> Removes a specific value from the symbol table. 
-  Returns the removed value.</dd>
-
-  <dt><tt>bool strip()</tt>:</dt>
-  <dd> This method will strip the symbol table of its names leaving
-  the type and values. </dd>
-
-  <dt><tt>void clear()</tt>:</dt>
-  <dd>Empty the symbol table completely.</dd>
-</dl>
-
-<h3>Iteration</h3>
-<p>The following functions describe three types of iterators you can obtain
-the beginning or end of the sequence for both const and non-const. It is
-important to keep track of the different kinds of iterators. There are
-three idioms worth pointing out:</p>
-<table>
-  <tr><th>Units</th><th>Iterator</th><th>Idiom</th></tr>
-  <tr>
-    <td align="left">Planes Of name/Value maps</td><td>PI</td>
-    <td align="left"><pre><tt>
-for (SymbolTable::plane_const_iterator PI = ST.plane_begin(),
-     PE = ST.plane_end(); PI != PE; ++PI ) {
-  PI-&gt;first // This is the Type* of the plane
-  PI-&gt;second // This is the SymbolTable::ValueMap of name/Value pairs
-    </tt></pre></td>
-  </tr>
-  <tr>
-    <td align="left">All name/Type Pairs</td><td>TI</td>
-    <td align="left"><pre><tt>
-for (SymbolTable::type_const_iterator TI = ST.type_begin(),
-     TE = ST.type_end(); TI != TE; ++TI )
-  TI-&gt;first  // This is the name of the type
-  TI-&gt;second // This is the Type* value associated with the name
-    </tt></pre></td>
-  </tr>
-  <tr>
-    <td align="left">name/Value pairs in a plane</td><td>VI</td>
-    <td align="left"><pre><tt>
-for (SymbolTable::value_const_iterator VI = ST.value_begin(SomeType),
-     VE = ST.value_end(SomeType); VI != VE; ++VI )
-  VI-&gt;first  // This is the name of the Value
-  VI-&gt;second // This is the Value* value associated with the name
-    </tt></pre></td>
-  </tr>
-</table>
-
-<p>Using the recommended iterator names and idioms will help you avoid
-making mistakes. Of particular note, make sure that whenever you use
-value_begin(SomeType) that you always compare the resulting iterator
-with value_end(SomeType) not value_end(SomeOtherType) or else you 
-will loop infinitely.</p>
-
-<dl>
-
-  <dt><tt>plane_iterator plane_begin()</tt>:</dt>
-  <dd>Get an iterator that starts at the beginning of the type planes.
-  The iterator will iterate over the Type/ValueMap pairs in the
-  type planes. </dd>
-
-  <dt><tt>plane_const_iterator plane_begin() const</tt>:</dt>
-  <dd>Get a const_iterator that starts at the beginning of the type 
-  planes.  The iterator will iterate over the Type/ValueMap pairs 
-  in the type planes. </dd>
-
-  <dt><tt>plane_iterator plane_end()</tt>:</dt>
-  <dd>Get an iterator at the end of the type planes. This serves as
-  the marker for end of iteration over the type planes.</dd>
-
-  <dt><tt>plane_const_iterator plane_end() const</tt>:</dt>
-  <dd>Get a const_iterator at the end of the type planes. This serves as
-  the marker for end of iteration over the type planes.</dd>
-
-  <dt><tt>value_iterator value_begin(const Type *Typ)</tt>:</dt>
-  <dd>Get an iterator that starts at the beginning of a type plane.
-  The iterator will iterate over the name/value pairs in the type plane.
-  Note: The type plane must already exist before using this.</dd>
-
-  <dt><tt>value_const_iterator value_begin(const Type *Typ) const</tt>:</dt>
-  <dd>Get a const_iterator that starts at the beginning of a type plane.
-  The iterator will iterate over the name/value pairs in the type plane.
-  Note: The type plane must already exist before using this.</dd>
-
-  <dt><tt>value_iterator value_end(const Type *Typ)</tt>:</dt>
-  <dd>Get an iterator to the end of a type plane. This serves as the marker
-  for end of iteration of the type plane.
-  Note: The type plane must already exist before using this.</dd>
-
-  <dt><tt>value_const_iterator value_end(const Type *Typ) const</tt>:</dt>
-  <dd>Get a const_iterator to the end of a type plane. This serves as the
-  marker for end of iteration of the type plane.
-  Note: the type plane must already exist before using this.</dd>
-
-  <dt><tt>type_iterator type_begin()</tt>:</dt>
-  <dd>Get an iterator to the start of the name/Type map.</dd>
-
-  <dt><tt>type_const_iterator type_begin() cons</tt>:</dt>
-  <dd> Get a const_iterator to the start of the name/Type map.</dd>
-
-  <dt><tt>type_iterator type_end()</tt>:</dt>
-  <dd>Get an iterator to the end of the name/Type map. This serves as the
-  marker for end of iteration of the types.</dd>
-
-  <dt><tt>type_const_iterator type_end() const</tt>:</dt>
-  <dd>Get a const-iterator to the end of the name/Type map. This serves 
-  as the marker for end of iteration of the types.</dd>
-
-  <dt><tt>plane_const_iterator find(const Type* Typ ) const</tt>:</dt>
-  <dd>This method returns a plane_const_iterator for iteration over
-  the type planes starting at a specific plane, given by \p Ty.</dd>
-
-  <dt><tt>plane_iterator find( const Type* Typ </tt>:</dt>
-  <dd>This method returns a plane_iterator for iteration over the
-  type planes starting at a specific plane, given by \p Ty.</dd>
-
-</dl>
-</div>
-
 <!-- *********************************************************************** -->
 <hr>
 <address>