Skip to content

Commit 15798f4

Browse files
AaronBallmanAaronBallman
authored
Move documentation about -verify from a header to public docs (#73694)
The internals manual seems like a more obvious home for the details instead of hiding them away in a header file and relying on doxygen output to document it publicly.
1 parent 437a48b commit 15798f4

File tree

2 files changed

+169
-150
lines changed

2 files changed

+169
-150
lines changed

‎clang/docs/InternalsManual.rst

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3309,6 +3309,173 @@ are similar.
33093309
as syntax highlighting, cross-referencing, and so on. The
33103310
``c-index-test`` helper program can be used to test these features.
33113311

3312+
Testing
3313+
-------
3314+
All functional changes to Clang should come with test coverage demonstrating
3315+
the change in behavior.
3316+
3317+
Verifying Diagnostics
3318+
^^^^^^^^^^^^^^^^^^^^^
3319+
Clang ``-cc1`` supports the ``-verify`` command line option as a way to
3320+
validate diagnostic behavior. This option will use special comments within the
3321+
test file to verify that expected diagnostics appear in the correct source
3322+
locations. If all of the expected diagnostics match the actual output of Clang,
3323+
then the invocation will return normally. If there are discrepancies between
3324+
the expected and actual output, Clang will emit detailed information about
3325+
which expected diagnostics were not seen or which unexpected diagnostics were
3326+
seen, etc. A complete example is:
3327+
3328+
.. code-block: c++
3329+
3330+
// RUN: %clang_cc1 -verify %s
3331+
int A = B; // expected-error {{use of undeclared identifier 'B'}}
3332+
3333+
If the test is run and the expected error is emitted on the expected line, the
3334+
diagnostic verifier will pass. However, if the expected error does not appear
3335+
or appears in a different location than expected, or if additional diagnostics
3336+
appear, the diagnostic verifier will fail and emit information as to why.
3337+
3338+
The ``-verify`` command optionally accepts a comma-delimited list of one or
3339+
more verification prefixes that can be used to craft those special comments.
3340+
Each prefix must start with a letter and contain only alphanumeric characters,
3341+
hyphens, and underscores. ``-verify`` by itself is equivalent to
3342+
``-verify=expected``, meaning that special comments will start with
3343+
``expected``. Using different prefixes makes it easier to have separate
3344+
``RUN:`` lines in the same test file which result in differing diagnostic
3345+
behavior. For example:
3346+
3347+
.. code-block:: c++
3348+
3349+
// RUN: %clang_cc1 -verify=foo,bar %s
3350+
3351+
int A = B; // foo-error {{use of undeclared identifier 'B'}}
3352+
int C = D; // bar-error {{use of undeclared identifier 'D'}}
3353+
int E = F; // expected-error {{use of undeclared identifier 'F'}}
3354+
3355+
The verifier will recognize ``foo-error`` and ``bar-error`` as special comments
3356+
but will not recognize ``expected-error`` as one because the ``-verify`` line
3357+
does not contain that as a prefix. Thus, this test would fail verification
3358+
because an unexpected diagnostic would appear on the declaration of ``E``.
3359+
3360+
Multiple occurrences accumulate prefixes. For example,
3361+
``-verify -verify=foo,bar -verify=baz`` is equivalent to
3362+
``-verify=expected,foo,bar,baz``.
3363+
3364+
Specifying Diagnostics
3365+
^^^^^^^^^^^^^^^^^^^^^^
3366+
Indicating that a line expects an error or a warning is simple. Put a comment
3367+
on the line that has the diagnostic, use
3368+
``expected-{error,warning,remark,note}`` to tag if it's an expected error,
3369+
warning, remark, or note (respectively), and place the expected text between
3370+
``{{`` and ``}}`` markers. The full text doesn't have to be included, only
3371+
enough to ensure that the correct diagnostic was emitted. (Note: full text
3372+
should be included in test cases unless there is a compelling reason to use
3373+
truncated text instead.)
3374+
3375+
Here's an example of the most commonly used way to specify expected
3376+
diagnostics:
3377+
3378+
.. code-block: c++
3379+
3380+
int A = B; // expected-error {{use of undeclared identifier 'B'}}
3381+
3382+
You can place as many diagnostics on one line as you wish. To make the code
3383+
more readable, you can use slash-newline to separate out the diagnostics.
3384+
3385+
Alternatively, it is possible to specify the line on which the diagnostic
3386+
should appear by appending ``@<line>`` to ``expected-<type>``, for example:
3387+
3388+
.. code-block: c++
3389+
3390+
#warning some text
3391+
// expected-warning@10 {{some text}}
3392+
3393+
The line number may be absolute (as above), or relative to the current line by
3394+
prefixing the number with either ``+`` or ``-``.
3395+
3396+
If the diagnostic is generated in a separate file, for example in a shared
3397+
header file, it may be beneficial to be able to declare the file in which the
3398+
diagnostic will appear, rather than placing the ``expected-*`` directive in the
3399+
actual file itself. This can be done using the following syntax:
3400+
3401+
.. code-block: c++
3402+
3403+
// expected-error@path/include.h:15 {{error message}}
3404+
3405+
The path can be absolute or relative and the same search paths will be used as
3406+
for ``#include`` directives. The line number in an external file may be
3407+
substituted with ``*`` meaning that any line number will match (useful where
3408+
the included file is, for example, a system header where the actual line number
3409+
may change and is not critical).
3410+
3411+
As an alternative to specifying a fixed line number, the location of a
3412+
diagnostic can instead be indicated by a marker of the form ``#<marker>``.
3413+
Markers are specified by including them in a comment, and then referenced by
3414+
appending the marker to the diagnostic with ``@#<marker>``, as with:
3415+
3416+
.. code-block: c++
3417+
3418+
#warning some text // #1
3419+
// ... other code ...
3420+
// expected-warning@#1 {{some text}}
3421+
3422+
The name of a marker used in a directive must be unique within the compilation.
3423+
3424+
The simple syntax above allows each specification to match exactly one
3425+
diagnostic. You can use the extended syntax to customize this. The extended
3426+
syntax is ``expected-<type> <n> {{diag text}}``, where ``<type>`` is one of
3427+
``error``, ``warning``, ``remark``, or ``note``, and ``<n>`` is a positive
3428+
integer. This allows the diagnostic to appear as many times as specified. For
3429+
example:
3430+
3431+
.. code-block: c++
3432+
3433+
void f(); // expected-note 2 {{previous declaration is here}}
3434+
3435+
Where the diagnostic is expected to occur a minimum number of times, this can
3436+
be specified by appending a ``+`` to the number. For example:
3437+
3438+
.. code-block: c++
3439+
3440+
void f(); // expected-note 0+ {{previous declaration is here}}
3441+
void g(); // expected-note 1+ {{previous declaration is here}}
3442+
3443+
In the first example, the diagnostic becomes optional, i.e. it will be
3444+
swallowed if it occurs, but will not generate an error if it does not occur. In
3445+
the second example, the diagnostic must occur at least once. As a short-hand,
3446+
"one or more" can be specified simply by ``+``. For example:
3447+
3448+
.. code-block: c++
3449+
3450+
void g(); // expected-note + {{previous declaration is here}}
3451+
3452+
A range can also be specified by ``<n>-<m>``. For example:
3453+
3454+
.. code-block: c++
3455+
3456+
void f(); // expected-note 0-1 {{previous declaration is here}}
3457+
3458+
In this example, the diagnostic may appear only once, if at all.
3459+
3460+
Regex matching mode may be selected by appending ``-re`` to the diagnostic type
3461+
and including regexes wrapped in double curly braces in the directive, such as:
3462+
3463+
.. code-block: c++
3464+
3465+
expected-error-re {{format specifies type 'wchar_t **' (aka '{{.+}}')}}
3466+
3467+
Examples matching error: "variable has incomplete type 'struct s'"
3468+
3469+
.. code-block: c++
3470+
3471+
// expected-error {{variable has incomplete type 'struct s'}}
3472+
// expected-error {{variable has incomplete type}}
3473+
3474+
// expected-error-re {{variable has type 'struct {{.}}'}}
3475+
// expected-error-re {{variable has type 'struct {{.*}}'}}
3476+
// expected-error-re {{variable has type 'struct {{(.*)}}'}}
3477+
// expected-error-re {{variable has type 'struct{{[[:space:]](.*)}}'}}
3478+
33123479
Feature Test Macros
33133480
===================
33143481
Clang implements several ways to test whether a feature is supported or not.

‎clang/include/clang/Frontend/VerifyDiagnosticConsumer.h

Lines changed: 2 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -32,156 +32,8 @@ class TextDiagnosticBuffer;
3232

3333
/// VerifyDiagnosticConsumer - Create a diagnostic client which will use
3434
/// markers in the input source to check that all the emitted diagnostics match
35-
/// those expected.
36-
///
37-
/// INVOKING THE DIAGNOSTIC CHECKER:
38-
///
39-
/// VerifyDiagnosticConsumer is typically invoked via the "-verify" option to
40-
/// "clang -cc1". "-verify" is equivalent to "-verify=expected", so all
41-
/// diagnostics are typically specified with the prefix "expected". For
42-
/// example:
43-
///
44-
/// \code
45-
/// int A = B; // expected-error {{use of undeclared identifier 'B'}}
46-
/// \endcode
47-
///
48-
/// Custom prefixes can be specified as a comma-separated sequence. Each
49-
/// prefix must start with a letter and contain only alphanumeric characters,
50-
/// hyphens, and underscores. For example, given just "-verify=foo,bar",
51-
/// the above diagnostic would be ignored, but the following diagnostics would
52-
/// be recognized:
53-
///
54-
/// \code
55-
/// int A = B; // foo-error {{use of undeclared identifier 'B'}}
56-
/// int C = D; // bar-error {{use of undeclared identifier 'D'}}
57-
/// \endcode
58-
///
59-
/// Multiple occurrences accumulate prefixes. For example,
60-
/// "-verify -verify=foo,bar -verify=baz" is equivalent to
61-
/// "-verify=expected,foo,bar,baz".
62-
///
63-
/// SPECIFYING DIAGNOSTICS:
64-
///
65-
/// Indicating that a line expects an error or a warning is simple. Put a
66-
/// comment on the line that has the diagnostic, use:
67-
///
68-
/// \code
69-
/// expected-{error,warning,remark,note}
70-
/// \endcode
71-
///
72-
/// to tag if it's an expected error, remark or warning, and place the expected
73-
/// text between {{ and }} markers. The full text doesn't have to be included,
74-
/// only enough to ensure that the correct diagnostic was emitted.
75-
///
76-
/// Here's an example:
77-
///
78-
/// \code
79-
/// int A = B; // expected-error {{use of undeclared identifier 'B'}}
80-
/// \endcode
81-
///
82-
/// You can place as many diagnostics on one line as you wish. To make the code
83-
/// more readable, you can use slash-newline to separate out the diagnostics.
84-
///
85-
/// Alternatively, it is possible to specify the line on which the diagnostic
86-
/// should appear by appending "@<line>" to "expected-<type>", for example:
87-
///
88-
/// \code
89-
/// #warning some text
90-
/// // expected-warning@10 {{some text}}
91-
/// \endcode
92-
///
93-
/// The line number may be absolute (as above), or relative to the current
94-
/// line by prefixing the number with either '+' or '-'.
95-
///
96-
/// If the diagnostic is generated in a separate file, for example in a shared
97-
/// header file, it may be beneficial to be able to declare the file in which
98-
/// the diagnostic will appear, rather than placing the expected-* directive in
99-
/// the actual file itself. This can be done using the following syntax:
100-
///
101-
/// \code
102-
/// // expected-error@path/include.h:15 {{error message}}
103-
/// \endcode
104-
///
105-
/// The path can be absolute or relative and the same search paths will be used
106-
/// as for #include directives. The line number in an external file may be
107-
/// substituted with '*' meaning that any line number will match (useful where
108-
/// the included file is, for example, a system header where the actual line
109-
/// number may change and is not critical).
110-
///
111-
/// As an alternative to specifying a fixed line number, the location of a
112-
/// diagnostic can instead be indicated by a marker of the form "#<marker>".
113-
/// Markers are specified by including them in a comment, and then referenced
114-
/// by appending the marker to the diagnostic with "@#<marker>":
115-
///
116-
/// \code
117-
/// #warning some text // #1
118-
/// // expected-warning@#1 {{some text}}
119-
/// \endcode
120-
///
121-
/// The name of a marker used in a directive must be unique within the
122-
/// compilation.
123-
///
124-
/// The simple syntax above allows each specification to match exactly one
125-
/// error. You can use the extended syntax to customize this. The extended
126-
/// syntax is "expected-<type> <n> {{diag text}}", where \<type> is one of
127-
/// "error", "warning" or "note", and \<n> is a positive integer. This allows
128-
/// the diagnostic to appear as many times as specified. Example:
129-
///
130-
/// \code
131-
/// void f(); // expected-note 2 {{previous declaration is here}}
132-
/// \endcode
133-
///
134-
/// Where the diagnostic is expected to occur a minimum number of times, this
135-
/// can be specified by appending a '+' to the number. Example:
136-
///
137-
/// \code
138-
/// void f(); // expected-note 0+ {{previous declaration is here}}
139-
/// void g(); // expected-note 1+ {{previous declaration is here}}
140-
/// \endcode
141-
///
142-
/// In the first example, the diagnostic becomes optional, i.e. it will be
143-
/// swallowed if it occurs, but will not generate an error if it does not
144-
/// occur. In the second example, the diagnostic must occur at least once.
145-
/// As a short-hand, "one or more" can be specified simply by '+'. Example:
146-
///
147-
/// \code
148-
/// void g(); // expected-note + {{previous declaration is here}}
149-
/// \endcode
150-
///
151-
/// A range can also be specified by "<n>-<m>". Example:
152-
///
153-
/// \code
154-
/// void f(); // expected-note 0-1 {{previous declaration is here}}
155-
/// \endcode
156-
///
157-
/// In this example, the diagnostic may appear only once, if at all.
158-
///
159-
/// Regex matching mode may be selected by appending '-re' to type and
160-
/// including regexes wrapped in double curly braces in the directive, such as:
161-
///
162-
/// \code
163-
/// expected-error-re {{format specifies type 'wchar_t **' (aka '{{.+}}')}}
164-
/// \endcode
165-
///
166-
/// Examples matching error: "variable has incomplete type 'struct s'"
167-
///
168-
/// \code
169-
/// // expected-error {{variable has incomplete type 'struct s'}}
170-
/// // expected-error {{variable has incomplete type}}
171-
///
172-
/// // expected-error-re {{variable has type 'struct {{.}}'}}
173-
/// // expected-error-re {{variable has type 'struct {{.*}}'}}
174-
/// // expected-error-re {{variable has type 'struct {{(.*)}}'}}
175-
/// // expected-error-re {{variable has type 'struct{{[[:space:]](.*)}}'}}
176-
/// \endcode
177-
///
178-
/// VerifyDiagnosticConsumer expects at least one expected-* directive to
179-
/// be found inside the source code. If no diagnostics are expected the
180-
/// following directive can be used to indicate this:
181-
///
182-
/// \code
183-
/// // expected-no-diagnostics
184-
/// \endcode
35+
/// those expected. See clang/docs/InternalsManual.rst for details about how to
36+
/// write tests to verify diagnostics.
18537
///
18638
class VerifyDiagnosticConsumer: public DiagnosticConsumer,
18739
public CommentHandler {

0 commit comments

Comments
 (0)