Fix ALL the markup.
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@148219 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/www/diagnostics.html b/www/diagnostics.html
index b3b168b..45f6907 100644
--- a/www/diagnostics.html
+++ b/www/diagnostics.html
@@ -4,10 +4,14 @@
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<title>Clang - Expressive Diagnostics</title>
- <link type="text/css" rel="stylesheet" href="menu.css" />
- <link type="text/css" rel="stylesheet" href="content.css" />
+ <link type="text/css" rel="stylesheet" href="menu.css">
+ <link type="text/css" rel="stylesheet" href="content.css">
<style type="text/css">
-</style>
+ .warn { color:magenta; }
+ .err { color:red; }
+ .snip { color:darkgreen; }
+ .point { color:blue; }
+ </style>
</head>
<body>
@@ -35,14 +39,14 @@
<p>First, all diagnostics produced by clang include full column number
information. The clang command-line compiler driver uses this information
-to print "caret diagnostics".
+to print "point diagnostics".
(IDEs can use the information to display in-line error markup.)
Precise error location in the source is a feature provided by many commercial
compilers, but is generally missing from open source
compilers. This is nice because it makes it very easy to understand exactly
what is wrong in a particular piece of code</p>
-<p>The caret (the blue "^" character) exactly shows where the problem is, even
+<p>The point (the blue "^" character) exactly shows where the problem is, even
inside of a string. This makes it really easy to jump to the problem and
helps when multiple instances of the same character occur on a line. (We'll
revisit this more in following examples.)</p>
@@ -51,9 +55,9 @@
$ <b>gcc-4.2 -fsyntax-only -Wformat format-strings.c</b>
format-strings.c:91: warning: too few arguments for format
$ <b>clang -fsyntax-only format-strings.c</b>
- format-strings.c:91:13: <font color="magenta">warning:</font> '.*' specified field precision is missing a matching 'int' argument
- <font color="darkgreen"> printf("%.*d");</font>
- <font color="blue"> ^</font>
+ format-strings.c:91:13: <span class="warn">warning:</span> '.*' specified field precision is missing a matching 'int' argument
+ <span class="snip"> printf("%.*d");</span>
+ <span class="point"> ^</span>
</pre>
<h2>Range Highlighting for Related Text</h2>
@@ -63,7 +67,7 @@
diagnostics highlight related information. In the following somewhat
nonsensical example you can see that you don't even need to see the original source code to
understand what is wrong based on the Clang error. Because clang prints a
-caret, you know exactly <em>which</em> plus it is complaining about. The range
+point, you know exactly <em>which</em> plus it is complaining about. The range
information highlights the left and right side of the plus which makes it
immediately obvious what the compiler is talking about.
Range information is very useful for
@@ -73,9 +77,9 @@
$ <b>gcc-4.2 -fsyntax-only t.c</b>
t.c:7: error: invalid operands to binary + (have 'int' and 'struct A')
$ <b>clang -fsyntax-only t.c</b>
- t.c:7:39: <font color="red">error:</font> invalid operands to binary expression ('int' and 'struct A')
- <font color="darkgreen"> return y + func(y ? ((SomeA.X + 40) + SomeA) / 42 + SomeA.X : SomeA.X);</font>
- <font color="blue"> ~~~~~~~~~~~~~~ ^ ~~~~~</font>
+ t.c:7:39: <span class="err">error:</span> invalid operands to binary expression ('int' and 'struct A')
+ <span class="snip"> return y + func(y ? ((SomeA.X + 40) + SomeA) / 42 + SomeA.X : SomeA.X);</span>
+ <span class="point"> ~~~~~~~~~~~~~~ ^ ~~~~~</span>
</pre>
<h2>Precision in Wording</h2>
@@ -84,7 +88,7 @@
out of clang contain exactly the pertinent information about what is wrong and
why. In the example above, we tell you what the inferred types are for
the left and right hand sides, and we don't repeat what is obvious from the
-caret (e.g., that this is a "binary +").</p>
+point (e.g., that this is a "binary +").</p>
<p>Many other examples abound. In the following example, not only do we tell you that there is a problem with the *
and point to it, we say exactly why and tell you what the type is (in case it is
@@ -96,9 +100,9 @@
$ <b>gcc-4.2 -fsyntax-only t.c</b>
t.c:5: error: invalid type argument of 'unary *'
$ <b>clang -fsyntax-only t.c</b>
- t.c:5:11: <font color="red">error:</font> indirection requires pointer operand ('int' invalid)
- <font color="darkgreen"> int y = *SomeA.X;</font>
- <font color="blue"> ^~~~~~~~</font>
+ t.c:5:11: <span class="err">error:</span> indirection requires pointer operand ('int' invalid)
+ <span class="snip"> int y = *SomeA.X;</span>
+ <span class="point"> ^~~~~~~~</span>
</pre>
<h2>No Pretty Printing of Expressions in Diagnostics</h2>
@@ -111,9 +115,9 @@
$ <b>gcc-4.2 -fsyntax-only t.c</b>
#'exact_div_expr' not supported by pp_c_expression#'t.c:12: error: called object is not a function
$ <b>clang -fsyntax-only t.c</b>
- t.c:12:8: <font color="red">error:</font> called object type 'int' is not a function or function pointer
- <font color="darkgreen"> (P-Q)();</font>
- <font color="blue"> ~~~~~^</font>
+ t.c:12:8: <span class="err">error:</span> called object type 'int' is not a function or function pointer
+ <span class="snip"> (P-Q)();</span>
+ <span class="point"> ~~~~~^</span>
</pre>
<p>This can be particularly bad in G++, which often emits errors
@@ -136,9 +140,9 @@
t.cc:9: error: no match for 'operator+' in '(((a*)P) + (*(long int*)(P->foo::<anonymous>.a::_vptr$a + -0x00000000000000020)))->a::bar() + * P'
t.cc:9: error: return-statement with a value, in function returning 'void'
$ <b>clang t.cc</b>
- t.cc:9:18: <font color="red">error:</font> invalid operands to binary expression ('int' and 'foo')
- <font color="darkgreen"> return P->bar() + *P;</font>
- <font color="blue"> ~~~~~~~~ ^ ~~</font>
+ t.cc:9:18: <span class="err">error:</span> invalid operands to binary expression ('int' and 'foo')
+ <span class="snip"> return P->bar() + *P;</span>
+ <span class="point"> ~~~~~~~~ ^ ~~</span>
</pre>
@@ -160,9 +164,9 @@
$ <b>gcc-4.2 -fsyntax-only t.c</b>
t.c:15: error: invalid operands to binary / (have 'float __vector__' and 'const int *')
$ <b>clang -fsyntax-only t.c</b>
- t.c:15:11: <font color="red">error:</font> can't convert between vector values of different size ('__m128' and 'int const *')
- <font color="darkgreen"> myvec[1]/P;</font>
- <font color="blue"> ~~~~~~~~^~</font>
+ t.c:15:11: <span class="err">error:</span> can't convert between vector values of different size ('__m128' and 'int const *')
+ <span class="snip"> myvec[1]/P;</span>
+ <span class="point"> ~~~~~~~~^~</span>
</pre>
<p>The following example shows where it is useful for the compiler to expose
@@ -173,9 +177,9 @@
$ <b>gcc-4.2 -fsyntax-only t.c</b>
t.c:13: error: request for member 'x' in something not a structure or union
$ <b>clang -fsyntax-only t.c</b>
- t.c:13:9: <font color="red">error:</font> member reference base type 'pid_t' (aka 'int') is not a structure or union
- <font color="darkgreen"> myvar = myvar.x;</font>
- <font color="blue"> ~~~~~ ^</font>
+ t.c:13:9: <span class="err">error:</span> member reference base type 'pid_t' (aka 'int') is not a structure or union
+ <span class="snip"> myvar = myvar.x;</span>
+ <span class="point"> ~~~~~ ^</span>
</pre>
<p>In C++, type preservation includes retaining any qualification written into type names. For example, if we take a small snippet of code such as:
@@ -204,9 +208,9 @@
$ <b>g++-4.2 -fsyntax-only t.cpp</b>
t.cpp:9: error: no match for 'operator+=' in 'server += http'
$ <b>clang -fsyntax-only t.cpp</b>
- t.cpp:9:10: <font color="red">error:</font> invalid operands to binary expression ('servers::Server const' and '::services::WebService const *')
- <font color="darkgreen">server += http;</font>
- <font color="blue">~~~~~~ ^ ~~~~</font>
+ t.cpp:9:10: <span class="err">error:</span> invalid operands to binary expression ('servers::Server const' and '::services::WebService const *')
+ <span class="snip">server += http;</span>
+ <span class="point">~~~~~~ ^ ~~~~</span>
</pre>
<p>Naturally, type preservation extends to uses of templates, and Clang retains information about how a particular template specialization (like <code>std::vector<Real></code>) was spelled within the source code. For example:</p>
@@ -215,9 +219,9 @@
$ <b>g++-4.2 -fsyntax-only t.cpp</b>
t.cpp:12: error: no match for 'operator=' in 'str = vec'
$ <b>clang -fsyntax-only t.cpp</b>
- t.cpp:12:7: <font color="red">error:</font> incompatible type assigning 'vector<Real>', expected 'std::string' (aka 'class std::basic_string<char>')
- <font color="darkgreen">str = vec</font>;
- <font color="blue">^ ~~~</font>
+ t.cpp:12:7: <span class="err">error:</span> incompatible type assigning 'vector<Real>', expected 'std::string' (aka 'class std::basic_string<char>')
+ <span class="snip">str = vec</span>;
+ <span class="point">^ ~~~</span>
</pre>
<h2>Fix-it Hints</h2>
@@ -230,18 +234,18 @@
problem. In the following example, Clang warns about the use of a GCC
extension that has been considered obsolete since 1993. The underlined
code should be removed, then replaced with the code below the
-caret line (".x =" or ".y =", respectively).</p>
+point line (".x =" or ".y =", respectively).</p>
<pre>
$ <b>clang t.c</b>
- t.c:5:28: <font color="magenta">warning:</font> use of GNU old-style field designator extension
- <font color="darkgreen">struct point origin = { x: 0.0, y: 0.0 };</font>
- <font color="red">~~</font> <font color="blue">^</font>
- <font color="darkgreen">.x = </font>
- t.c:5:36: <font color="magenta">warning:</font> use of GNU old-style field designator extension
- <font color="darkgreen">struct point origin = { x: 0.0, y: 0.0 };</font>
- <font color="red">~~</font> <font color="blue">^</font>
- <font color="darkgreen">.y = </font>
+ t.c:5:28: <span class="warn">warning:</span> use of GNU old-style field designator extension
+ <span class="snip">struct point origin = { x: 0.0, y: 0.0 };</span>
+ <span class="err">~~</span> <span class="point">^</span>
+ <span class="snip">.x = </span>
+ t.c:5:36: <span class="warn">warning:</span> use of GNU old-style field designator extension
+ <span class="snip">struct point origin = { x: 0.0, y: 0.0 };</span>
+ <span class="err">~~</span> <span class="point">^</span>
+ <span class="snip">.y = </span>
</pre>
<p>"Fix-it" hints are most useful for
@@ -253,10 +257,10 @@
<pre>
$ <b>clang t.cpp</b>
- t.cpp:9:3: <font color="red">error:</font> template specialization requires 'template<>'
+ t.cpp:9:3: <span class="err">error:</span> template specialization requires 'template<>'
struct iterator_traits<file_iterator> {
- <font color="blue">^</font>
- <font color="darkgreen">template<> </font>
+ <span class="point">^</span>
+ <span class="snip">template<> </span>
</pre>
<h2>Automatic Macro Expansion</h2>
@@ -273,12 +277,12 @@
t.c: In function 'test':
t.c:80: error: invalid operands to binary < (have 'struct mystruct' and 'float')
$ <b>clang -fsyntax-only t.c</b>
- t.c:80:3: <font color="red">error:</font> invalid operands to binary expression ('typeof(P)' (aka 'struct mystruct') and 'typeof(F)' (aka 'float'))
- <font color="darkgreen"> X = MYMAX(P, F);</font>
- <font color="blue"> ^~~~~~~~~~~</font>
+ t.c:80:3: <span class="err">error:</span> invalid operands to binary expression ('typeof(P)' (aka 'struct mystruct') and 'typeof(F)' (aka 'float'))
+ <span class="snip"> X = MYMAX(P, F);</span>
+ <span class="point"> ^~~~~~~~~~~</span>
t.c:76:94: note: instantiated from:
- <font color="darkgreen">#define MYMAX(A,B) __extension__ ({ __typeof__(A) __a = (A); __typeof__(B) __b = (B); __a < __b ? __b : __a; })</font>
- <font color="blue"> ~~~ ^ ~~~</font>
+ <span class="snip">#define MYMAX(A,B) __extension__ ({ __typeof__(A) __a = (A); __typeof__(B) __b = (B); __a < __b ? __b : __a; })</span>
+ <span class="point"> ~~~ ^ ~~~</span>
</pre>
<p>Here's another real world warning that occurs in the "window" Unix package (which
@@ -286,15 +290,15 @@
<pre>
$ <b>clang -fsyntax-only t.c</b>
- t.c:22:2: <font color="magenta">warning:</font> type specifier missing, defaults to 'int'
- <font color="darkgreen"> ILPAD();</font>
- <font color="blue"> ^</font>
+ t.c:22:2: <span class="warn">warning:</span> type specifier missing, defaults to 'int'
+ <span class="snip"> ILPAD();</span>
+ <span class="point"> ^</span>
t.c:17:17: note: instantiated from:
- <font color="darkgreen">#define ILPAD() PAD((NROW - tt.tt_row) * 10) /* 1 ms per char */</font>
- <font color="blue"> ^</font>
+ <span class="snip">#define ILPAD() PAD((NROW - tt.tt_row) * 10) /* 1 ms per char */</span>
+ <span class="point"> ^</span>
t.c:14:2: note: instantiated from:
- <font color="darkgreen"> register i; \</font>
- <font color="blue"> ^</font>
+ <span class="snip"> register i; \</span>
+ <span class="point"> ^</span>
</pre>
<p>In practice, we've found that Clang's treatment of macros is actually more useful in multiply nested
@@ -308,7 +312,7 @@
<p>The following example shows a trivial little tweak, where we tell you to put the semicolon at
the end of the line that is missing it (line 4) instead of at the beginning of
the following line (line 5). This is particularly important with fixit hints
-and caret diagnostics, because otherwise you don't get the important context.
+and point diagnostics, because otherwise you don't get the important context.
</p>
<pre>
@@ -316,10 +320,10 @@
t.c: In function 'foo':
t.c:5: error: expected ';' before '}' token
$ <b>clang t.c</b>
- t.c:4:8: <font color="red">error:</font> expected ';' after expression
- <font color="darkgreen"> bar()</font>
- <font color="blue"> ^</font>
- <font color="blue"> ;</font>
+ t.c:4:8: <span class="err">error:</span> expected ';' after expression
+ <span class="snip"> bar()</span>
+ <span class="point"> ^</span>
+ <span class="point"> ;</span>
</pre>
<p>The following example shows much better error recovery than GCC. The message coming out
@@ -330,9 +334,9 @@
$ <b>gcc-4.2 t.c</b>
t.c:3: error: expected '=', ',', ';', 'asm' or '__attribute__' before '*' token
$ <b>clang t.c</b>
- t.c:3:1: <font color="red">error:</font> unknown type name 'foo_t'
- <font color="darkgreen">foo_t *P = 0;</font>
- <font color="blue">^</font>
+ t.c:3:1: <span class="err">error:</span> unknown type name 'foo_t'
+ <span class="snip">foo_t *P = 0;</span>
+ <span class="point">^</span>
</pre>
<p>The following example shows that we recover from the simple case of
@@ -352,14 +356,14 @@
t.cc:4: error: invalid type in declaration before ';' token
t.cc:6: error: expected unqualified-id at end of input
$ <b>clang t.cc</b>
- t.cc:2:11: <font color="red">error:</font> expected ';' after class
- <font color="darkgreen">class a {}</font>
- <font color="blue"> ^</font>
- <font color="blue"> ;</font>
- t.cc:6:2: <font color="red">error:</font> expected ';' after struct
- <font color="darkgreen">}</font>
- <font color="blue"> ^</font>
- <font color="blue"> ;</font>
+ t.cc:2:11: <span class="err">error:</span> expected ';' after class
+ <span class="snip">class a {}</span>
+ <span class="point"> ^</span>
+ <span class="point"> ;</span>
+ t.cc:6:2: <span class="err">error:</span> expected ';' after struct
+ <span class="snip">}</span>
+ <span class="point"> ^</span>
+ <span class="point"> ;</span>
</pre>
<p>While each of these details is minor, we feel that they all add up to provide