Implement PR3313, and while I'm at it address a very FAQ.

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

1 files changed, 38 insertions, 2 deletions

diff --git a/docs/LangRef.html b/docs/LangRef.html
index 9afc2259af..7b8d4f8c85 100644
--- a/docs/LangRef.html
+++ b/docs/LangRef.html
@@ -22,6 +22,7 @@
       <li><a href="#modulestructure">Module Structure</a></li>
       <li><a href="#linkage">Linkage Types</a></li>
       <li><a href="#callingconv">Calling Conventions</a></li>
+      <li><a href="#namedtypes">Named Types</a></li>
       <li><a href="#globalvars">Global Variables</a></li>
       <li><a href="#functionstructure">Functions</a></li>
       <li><a href="#aliasstructure">Aliases</a></li>
@@ -682,6 +683,41 @@ All Global Variables and Functions have one of the following visibility styles:
 
 <!-- ======================================================================= -->
 <div class="doc_subsection">
+  <a name="namedtypes">Named Types</a>
+</div>
+
+<div class="doc_text">
+
+<p>LLVM IR allows you to specify name aliases for certain types.  This can make
+it easier to read the IR and make the IR more condensed (particularly when
+recursive types are involved).  An example of a name specification is:
+</p>
+
+<div class="doc_code">
+<pre>
+%mytype = type { %mytype*, i32 }
+</pre>
+</div>
+
+<p>You may give a name to any <a href="#typesystem">type</a> except "<a 
+href="t_void">void</a>".  Type name aliases may be used anywhere a type is
+expected with the syntax "%mytype".</p>
+
+<p>Note that type names are aliases for the structural type that they indicate,
+and that you can therefore specify multiple names for the same type.  This often
+leads to confusing behavior when dumping out a .ll file.  Since LLVM IR uses
+structural typing, the name is not part of the type.  When printing out LLVM IR,
+the printer will pick <em>one name</em> to render all types of a particular
+shape.  This means that if you have code where two different source types end up
+having the same LLVM type, that the dumper will sometimes print the "wrong" or
+unexpected type.  This is an important design point and isn't going to
+change.</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
   <a name="globalvars">Global Variables</a>
 </div>
 
@@ -3425,8 +3461,8 @@ int *foo(struct ST *s) {
 
 <div class="doc_code">
 <pre>
-%RT = type { i8 , [10 x [20 x i32]], i8  }
-%ST = type { i32, double, %RT }
+%RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8  }
+%ST = <a href="#namedtypes">type</a> { i32, double, %RT }
 
 define i32* %foo(%ST* %s) {
 entry: