Update documentation with regards to template type diffing.

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

diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html
index ca870c4f75002067544c0ef73966d85a15c16cea..c97acd1ae0aae5285274c4bab869bbd76fcb18a2 100644 (file)
--- a/docs/InternalsManual.html
+++ b/docs/InternalsManual.html
@@ -357,6 +357,11 @@ Clang:</p>
 <tr><td>Example:</td><td><tt>"candidate found by name lookup is %q0"</tt></td></tr>
 <tr><td>Class:</td><td>NamedDecl*</td></tr>
 <tr><td>Description</td><td><p>This formatter indicates that the fully-qualified name of the declaration should be printed, e.g., "std::vector" rather than "vector".</p></td></tr>
+
+<tr><td colspan="2"><b>"diff" format</b></td></tr>
+<tr><td>Example:</td><td><tt>"no known conversion %diff{from | to | }1,2"</tt></td></tr>
+<tr><td>Class:</td><td>QualType</td></tr>
+<tr><td>Description</td><td><p>This formatter takes two QualTypes and attempts to print a template difference between the two.  If tree printing is off, the entire text inside the the braces, with the formatted text replacing the pipes.  If tree printing is on, the text is not printed and a type tree is printed after the diagnostic message.</p></td></tr>
     
 </table>
 

diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html
index 7bca3bf218984ea5f7b79bf866de2ea8e62d0842..b820e8dc3fdf1c17744dc87d7069b498862e056c 100644 (file)
--- a/docs/ReleaseNotes.html
+++ b/docs/ReleaseNotes.html
@@ -121,6 +121,55 @@ int f(bool b) {
   This functionality can be enabled or disabled separately from
   <tt>-Wuninitialized</tt> with the <tt>-Wsometimes-uninitialized</tt> warning
   flag.</li>
+
+  <li>Template type diffing improves the display of diagnostics with templated
+  types in them.
+
+<pre>
+int f(vector&lt;map&lt;int, double&gt;&gt;);
+int x = f(vector&lt;map&lt;int, float&gt;&gt;());
+</pre>
+  The error message is the same, but the note is different based on the options selected.
+<pre>
+<b>template-diff.cpp:5:9: <span class="error">error:</span> no matching function for call to 'f'</b>
+int x = f(vector&lt;map&lt;int, float&gt;&gt;());
+        <span class="caret">^</span>
+</pre>
+  Templated type diffing with type elision (default):
+<pre>
+<b>template-diff.cpp:4:5: <span class="note">note:</span></b> candidate function not viable: no known conversion from 'vector&lt;map&lt;[...], <span class="template-highlight">float</span>&gt;&gt;' to 'vector&lt;map&lt;[...], <span class="template-highlight">double</span>&gt;&gt;' for 1st argument;
+int f(vector&lt;map&lt;int, double&gt;&gt;);
+    <span class="caret">^</span>
+</pre>
+  Templated type diffing without type elision (-fno-elide-type):
+<pre>
+<b>template-diff.cpp:4:5: <span class="note">note:</span></b> candidate function not viable: no known conversion from 'vector&lt;map&lt;int, <span class="template-highlight">float</span>&gt;&gt;' to 'vector&lt;map&lt;int, <span class="template-highlight">double</span>&gt;&gt;' for 1st argument;
+int f(vector&lt;map&lt;int, double&gt;&gt;);
+    <span class="caret">^</span>
+</pre>
+  Templated tree printing with type elision (-fdiagnostics-show-template-tree):
+<pre>
+<b>template-diff.cpp:4:5: <span class="note">note:</span></b> candidate function not viable: no known conversion for 1st argument;
+  vector&lt;
+    map&lt;
+      [...],
+      [<span class="template-highlight">float</span> != <span class="template-highlight">double</span>]&gt;&gt;
+int f(vector&lt;map&lt;int, double&gt;&gt;);
+    <span class="caret">^</span>
+</pre>
+  Templated tree printing without type elision (-fdiagnostics-show-template-tree -fno-elide-type):
+<pre>
+<b>template-diff.cpp:4:5: <span class="note">note:</span></b> candidate function not viable: no known conversion for 1st argument;
+  vector&lt;
+    map&lt;
+      int,
+      [<span class="template-highlight">float</span> != <span class="template-highlight">double</span>]&gt;&gt;
+int f(vector&lt;map&lt;int, double&gt;&gt;);
+    <span class="caret">^</span>
+</pre>
+
+  </li>
+
 </ul>
 
 <h4 id="tlsmodel">Support for <code>tls_model</code> attribute</h4>

diff --git a/docs/UsersManual.html b/docs/UsersManual.html
index ae9ebfa394b9fdf441a06d630725589bea9df7cc..6a620d2018573edb726c31857c69e8533d269632 100644 (file)
--- a/docs/UsersManual.html
+++ b/docs/UsersManual.html
@@ -417,6 +417,48 @@ quotes(as "\"") and non-printable characters (as octal
 &quot;\xxx&quot;).</p>
 </dd>
 
+<dt id="opt_fno-elide-type">
+<b>-fno-elide-type</b>:
+Turns off elision in template type printing.</td>
+<dd><p>The default for template type printing is to elide as many template
+arguments as possible, removing those which are the same in both template types,
+leaving only the differences.  Adding this flag will print all the template
+arguments.  If supported by the terminal, highlighting will still appear on
+differing arguments.</p>
+
+Default:
+<pre>
+t.cc:4:5: <span class="note">note</span>: candidate function not viable: no known conversion from 'vector&lt;map&lt;[...], map&lt;<span class="template-highlight">float</span>, [...]&gt;&gt;&gt;' to 'vector&lt;map&lt;[...], map&lt;<span class="template-highlight">double</span>, [...]&gt;&gt;&gt;' for 1st argument;
+</pre>
+-fno-elide-type:
+<pre>
+t.cc:4:5: <span class="note">note</span>: candidate function not viable: no known conversion from 'vector&lt;map&lt;int, map&lt;<span class="template-highlight">float</span>, int&gt;&gt;&gt;' to 'vector&lt;map&lt;int, map&lt;<span class="template-highlight">double</span>, int&gt;&gt;&gt;' for 1st argument;
+</pre>
+</dd>
+
+<dt id="opt_fdiagnostics-show-template-tree">
+<b>-fdiagnostics-show-template-tree</b>:
+Template type diffing prints a text tree.</td>
+<dd><p>For diffing large templated types, this option will cause Clang to
+display the templates as an indented text tree, one argument per line, with
+differences marked inline.  This is compatible with -fno-elide-type.</p>
+
+Default:
+<pre>
+t.cc:4:5: <span class="note">note</span>: candidate function not viable: no known conversion from 'vector&lt;map&lt;[...], map&lt;<span class="template-highlight">float</span>, [...]&gt;&gt;&gt;' to 'vector&lt;map&lt;[...], map&lt;<span class="template-highlight">double</span>, [...]&gt;&gt;&gt;' for 1st argument;
+</pre>
+-fdiagnostics-show-template-tree
+<pre>
+t.cc:4:5: <span class="note">note</span>: candidate function not viable: no known conversion for 1st argument;
+  vector&lt;
+    map&lt;
+      [...],
+      map&lt;
+        [<span class="template-highlight">float</span> != <span class="template-highlight">float</span>],
+        [...]&gt;&gt;&gt;
+</pre>
+</dd>
+
 </dl>
 
 

diff --git a/www/content.css b/www/content.css
index b5925560b11666614d62606522d98ce9c15fd919..8572d7cae1d179cfed02639b44e3945077aeec00 100644 (file)
--- a/www/content.css
+++ b/www/content.css
@@ -27,6 +27,7 @@ span.error { color:red }
 span.warning { color:purple }
 span.note { color:gray }
 span.caret { color:green; font-weight:bold }
+span.template-highlight { color:cyan }
 
 /* Tables */
 tr { vertical-align:top }

diff --git a/www/diagnostics.html b/www/diagnostics.html
index 45f69074bcfdd852b9d3b36feae33d34f4974a85..84c6f8bc320ca9c528f32715ed4fc84685fd00f3 100644 (file)
--- a/www/diagnostics.html
+++ b/www/diagnostics.html
@@ -263,6 +263,39 @@ diagnostic.<p>
     <span class="snip">template&lt;&gt; </span>
 </pre>
 
+<h2>Template Type Diffing</h2>
+
+<p>Templates types can be long and difficult to read.  Moreso when part of an
+error message.  Instead of just printing out the type name, Clang has enough
+information to remove the common elements and highlight the differences.  To
+show the template structure more clearly, the templated type can also be
+printed as an indented text tree.</p>
+
+Default: template diff with type elision
+<pre>
+t.cc:4:5: <span class="note">note:</span> candidate function not viable: no known conversion from 'vector&lt;map&lt;[...], <span class="template-highlight">float</span>&gt;&gt;' to 'vector&lt;map&lt;[...], <span class="template-highlight">double</span>&gt;&gt;' for 1st argument;
+</pre>
+-fno-elide-type: template diff without elision
+<pre>
+t.cc:4:5: <span class="note">note:</span> candidate function not viable: no known conversion from 'vector&lt;map&lt;int, <span class="template-highlight">float</span>&gt;&gt;' to 'vector&lt;map&lt;int, <span class="template-highlight">double</span>&gt;&gt;' for 1st argument;
+</pre>
+-fdiagnostics-show-template-tree: template tree printing with elision
+<pre>
+t.cc:4:5: <span class="note">note:</span> candidate function not viable: no known conversion for 1st argument;
+  vector&lt;
+    map&lt;
+      [...], 
+      [<span class="template-highlight">float</span> != <span class="template-highlight">double</span>]&gt;&gt;
+</pre>
+-fdiagnostics-show-template-tree -fno-elide-type: template tree printing with no elision
+<pre>
+t.cc:4:5: <span class="note">note:M</span> candidate function not viable: no known conversion for 1st argument;
+  vector&lt;
+    map&lt;
+      int, 
+      [<span class="template-highlight">float</span> != <span class="template-highlight">double</span>]&gt;&gt;
+</pre>
+
 <h2>Automatic Macro Expansion</h2>
 
 <p>Many errors happen in macros that are sometimes deeply nested.  With