From 714257f5deec6049a4170bdd77ca1c3df989d67e Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin <jyasskin@google.com>
Date: Thu, 30 Apr 2009 22:33:41 +0000
Subject: [PATCH] Add a mention of TypeBuilder to the programmer's manual, and
 clean up the class comment a bit.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@70515 91177308-0d34-0410-b5e6-96231b3b80d8
---
 docs/ProgrammersManual.html        | 41 ++++++++++++++++++++++++++++++
 include/llvm/Support/TypeBuilder.h | 12 ++++-----
 2 files changed, 47 insertions(+), 6 deletions(-)

diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html
index e2525ae84e0..253e8363610 100644
--- a/docs/ProgrammersManual.html
+++ b/docs/ProgrammersManual.html
@@ -117,6 +117,7 @@ with another <tt>Value</tt></a> </li>
           <li><a href="#schanges_deletingGV">Deleting <tt>GlobalVariable</tt>s</a> </li>  
         </ul>
       </li>
+      <li><a href="#create_types">How to Create Types</a></li>
 <!--
     <li>Working with the Control Flow Graph
     <ul>
@@ -2088,6 +2089,46 @@ GV-&gt;eraseFromParent();
 
 </div>
 
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="create_types">How to Create Types</a>
+</div>
+
+<div class="doc_text">
+
+<p>In generating IR, you may need some complex types.  If you know these types
+statically, you can use <tt>TypeBuilder&lt;...>::get()</tt>, defined
+in <tt>llvm/Support/TypeBuilder.h</tt>, to retrieve them.  <tt>TypeBuilder</tt>
+has two forms depending on whether you're building types for cross-compilation
+or native library use.  <tt>TypeBuilder&lt;T, true></tt> requires
+that <tt>T</tt> be independent of the host environment, meaning that it's built
+out of types from
+the <a href="/doxygen/namespacellvm_1_1types.html"><tt>llvm::types</tt></a>
+namespace and pointers, functions, arrays, etc. built of
+those.  <tt>TypeBuilder&lt;T, false></tt> additionally allows native C types
+whose size may depend on the host compiler.  For example,</p>
+
+<div class="doc_code">
+<pre>
+FunctionType *ft = TypeBuilder&lt;types::i&lt;8>(types::i&lt;32>*), true>::get();
+</pre>
+</div>
+
+<p>is easier to read and write than the equivalent</p>
+
+<div class="doc_code">
+<pre>
+std::vector<const Type*> params;
+params.push_back(PointerType::getUnqual(Type::Int32Ty));
+FunctionType *ft = FunctionType::get(Type::Int8Ty, params, false);
+</pre>
+</div>
+
+<p>See the <a href="/doxygen/TypeBuilder_8h-source.html#l00001">class
+comment</a> for more details.</p>
+
+</div>
+
 <!-- *********************************************************************** -->
 <div class="doc_section">
   <a name="advanced">Advanced Topics</a>
diff --git a/include/llvm/Support/TypeBuilder.h b/include/llvm/Support/TypeBuilder.h
index df8bc5ea4ba..c8ffb938c60 100644
--- a/include/llvm/Support/TypeBuilder.h
+++ b/include/llvm/Support/TypeBuilder.h
@@ -40,21 +40,21 @@ namespace llvm {
 ///   int8 AFunction(struct MyType *value);
 ///
 /// You'll want to use
-///   Function::Create(TypeBuilder<types::i<8>(MyType*)>::get(), ...)
+///   Function::Create(TypeBuilder<types::i<8>(MyType*), true>::get(), ...)
 /// to declare the function, but when you first try this, your compiler will
-/// complain that TypeBuilder<MyType>::get() doesn't exist. To fix this, write:
+/// complain that TypeBuilder<MyType, true>::get() doesn't exist. To fix this,
+/// write:
 ///
 ///   namespace llvm {
-///   using types::i;
 ///   template<bool xcompile> class TypeBuilder<MyType, xcompile> {
 ///   public:
 ///     static const StructType *get() {
 ///       // Using the static result variable ensures that the type is
 ///       // only looked up once.
 ///       static const StructType *const result = StructType::get(
-///         TypeBuilder<i<32>, xcompile>::get(),
-///         TypeBuilder<i<32>*, xcompile>::get(),
-///         TypeBuilder<i<8>*[], xcompile>::get(),
+///         TypeBuilder<types::i<32>, xcompile>::get(),
+///         TypeBuilder<types::i<32>*, xcompile>::get(),
+///         TypeBuilder<types::i<8>*[], xcompile>::get(),
 ///         NULL);
 ///       return result;
 ///     }
-- 
2.34.1