From e59331ac3420d5028d986ada5c7ad826500d1e12 Mon Sep 17 00:00:00 2001 From: Richard Trieu Date: Wed, 27 Jun 2012 02:00:20 +0000 Subject: [PATCH] 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 --- docs/InternalsManual.html | 5 ++++ docs/ReleaseNotes.html | 49 +++++++++++++++++++++++++++++++++++++++ docs/UsersManual.html | 42 +++++++++++++++++++++++++++++++++ www/content.css | 1 + www/diagnostics.html | 33 ++++++++++++++++++++++++++ 5 files changed, 130 insertions(+) diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html index ca870c4f7500..c97acd1ae0aa 100644 --- a/docs/InternalsManual.html +++ b/docs/InternalsManual.html @@ -357,6 +357,11 @@

Formatting a Diagnostic Argument

Example:"candidate found by name lookup is %q0" Class:NamedDecl* Description

This formatter indicates that the fully-qualified name of the declaration should be printed, e.g., "std::vector" rather than "vector".

+ +"diff" format +Example:"no known conversion %diff{from | to | }1,2" +Class:QualType +Description

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.

diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html index 7bca3bf21898..b820e8dc3fdf 100644 --- a/docs/ReleaseNotes.html +++ b/docs/ReleaseNotes.html @@ -121,6 +121,55 @@

Improvements to Clang's diagnostics

This functionality can be enabled or disabled separately from -Wuninitialized with the -Wsometimes-uninitialized warning flag. + +
  • Template type diffing improves the display of diagnostics with templated + types in them. + +
    +int f(vector<map<int, double>>);
+int x = f(vector<map<int, float>>());
+
    + The error message is the same, but the note is different based on the options selected. +
    +template-diff.cpp:5:9: error: no matching function for call to 'f'
+int x = f(vector<map<int, float>>());
+        ^
+
    + Templated type diffing with type elision (default): +
    +template-diff.cpp:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], float>>' to 'vector<map<[...], double>>' for 1st argument;
+int f(vector<map<int, double>>);
+    ^
+
    + Templated type diffing without type elision (-fno-elide-type): +
    +template-diff.cpp:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, float>>' to 'vector<map<int, double>>' for 1st argument;
+int f(vector<map<int, double>>);
+    ^
+
    + Templated tree printing with type elision (-fdiagnostics-show-template-tree): +
    +template-diff.cpp:4:5: note: candidate function not viable: no known conversion for 1st argument;
+  vector<
+    map<
+      [...],
+      [float != double]>>
+int f(vector<map<int, double>>);
+    ^
+
    + Templated tree printing without type elision (-fdiagnostics-show-template-tree -fno-elide-type): +
    +template-diff.cpp:4:5: note: candidate function not viable: no known conversion for 1st argument;
+  vector<
+    map<
+      int,
+      [float != double]>>
+int f(vector<map<int, double>>);
+    ^
+
    + +
    • +

    Support for tls_model attribute

    diff --git a/docs/UsersManual.html b/docs/UsersManual.html index ae9ebfa394b9..6a620d201857 100644 --- a/docs/UsersManual.html +++ b/docs/UsersManual.html @@ -417,6 +417,48 @@

    Formatting of Diagnostics

    "\xxx").

    +
    +-fno-elide-type: +Turns off elision in template type printing. +

    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.

    + +Default: +
    +t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
+
    +-fno-elide-type: +
    +t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument;
+
    +
    + +
    +-fdiagnostics-show-template-tree: +Template type diffing prints a text tree. +

    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.

    + +Default: +
    +t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
+
    +-fdiagnostics-show-template-tree +
    +t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
+  vector<
+    map<
+      [...],
+      map<
+        [float != float],
+        [...]>>>
+
    +
    + diff --git a/www/content.css b/www/content.css index b5925560b116..8572d7cae1d1 100644 --- 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 45f69074bcfd..84c6f8bc320c 100644 --- a/www/diagnostics.html +++ b/www/diagnostics.html @@ -263,6 +263,39 @@

    Fix-it Hints

    template<> +

    Template Type Diffing

    + +

    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.

    + +Default: template diff with type elision +
    +t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], float>>' to 'vector<map<[...], double>>' for 1st argument;
+
    +-fno-elide-type: template diff without elision +
    +t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, float>>' to 'vector<map<int, double>>' for 1st argument;
+
    +-fdiagnostics-show-template-tree: template tree printing with elision +
    +t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
+  vector<
+    map<
+      [...], 
+      [float != double]>>
+
    +-fdiagnostics-show-template-tree -fno-elide-type: template tree printing with no elision +
    +t.cc:4:5: note:M candidate function not viable: no known conversion for 1st argument;
+  vector<
+    map<
+      int, 
+      [float != double]>>
+
    +

    Automatic Macro Expansion

    Many errors happen in macros that are sometimes deeply nested. With