[VerifyDiagnosticConsumer] Document -verify=<prefixes> in doxygen

[jdenny]

Summary

Previously, it was only documented by -cc1 -help, so people weren't
aware of it, as discussed in D60732.

[Charusso]

Thanks you!

I really like live working examples, I hope not just me. Could you link https://github.com/llvm/llvm-project/blob/master/clang/test/Analysis/use-after-move.cpp as well as a live example?

[NoQ]

Yup, i confirm that this improves discoverability of this feature :) Maybe it deserves its own .rst doc, like FileCheck, but for now doxygen seems to be the best source of truth on how to use -verify and i consult it regularly.

In D60845#1470980, @Charusso wrote:

I really like live working examples, I hope not just me. Could you link https://github.com/llvm/llvm-project/blob/master/clang/test/Analysis/use-after-move.cpp as well as a live example?

I'd rather reserve an ability for myself to move the test around without breaking links all over the place. Live examples are easy to grep for as soon as you know what to grep for.

[rsmith]

In D60845#1470986, @NoQ wrote:

Yup, i confirm that this improves discoverability of this feature :) Maybe it deserves its own .rst doc, like FileCheck, but for now doxygen seems to be the best source of truth on how to use -verify and i consult it regularly.

I've seen a few projects outside of clang use -verify mode for their own testing of various things. Maybe it's time we promote it from an internal self-testing tool to a full-fledged and supported part of Clang's interface (including adding a driver flag and a proper description in the user manual)?

[jdenny]

Clarify the behavior of multiple -verify options.

[jdenny]

Thanks for the accepts.

In D60845#1470986, @NoQ wrote:

In D60845#1470980, @Charusso wrote:

I really like live working examples, I hope not just me. Could you link https://github.com/llvm/llvm-project/blob/master/clang/test/Analysis/use-after-move.cpp as well as a live example?

I'd rather reserve an ability for myself to move the test around without breaking links all over the place. Live examples are easy to grep for as soon as you know what to grep for.

Agreed.

In D60845#1471002, @rsmith wrote:

I've seen a few projects outside of clang use -verify mode for their own testing of various things.

Interesting. What's an example?

[rsmith]

In D60845#1471741, @jdenny wrote:

In D60845#1471002, @rsmith wrote:

I've seen a few projects outside of clang use -verify mode for their own testing of various things.

Interesting. What's an example?

libc++ and absl both use -verify in their test suites.

[jdenny]

In D60845#1472291, @rsmith wrote:

In D60845#1471741, @jdenny wrote:

In D60845#1471002, @rsmith wrote:

I've seen a few projects outside of clang use -verify mode for their own testing of various things.

Interesting. What's an example?

libc++ and absl both use -verify in their test suites.

Thanks. I just took a quick glance at libc++. I see checks that the library manages to induce desired compiler diagnostics in code that incorrectly interfaces with the library. That's a nice capability to expose, especially for people writing C++ libraries.

clang/include/clang/Frontend/VerifyDiagnosticConsumer.h

 class LangOptions;
 class SourceManager;
 class TextDiagnosticBuffer;
 
 /// VerifyDiagnosticConsumer - Create a diagnostic client which will use
 /// markers in the input source to check that all the emitted diagnostics match
 /// those expected.
 ///
-/// USING THE DIAGNOSTIC CHECKER:
+/// INVOKING THE DIAGNOSTIC CHECKER:
+///
+/// VerifyDiagnosticConsumer is typically invoked via the "-verify" option to
+/// "clang -cc1".  "-verify" is equivalent to "-verify=expected", so all
+/// diagnostics are typically specified with the prefix "expected".  For
+/// example:
+///
+/// \code
+///   int A = B; // expected-error {{use of undeclared identifier 'B'}}
+/// \endcode
+///
+/// Custom prefixes can be specified as a comma-separated sequence.  Each
+/// prefix must start with a letter and contain only alphanumeric characters,
+/// hyphens, and underscores.  For example, given just "-verify=foo,bar",
+/// the above diagnostic would be ignored, but the following diagnostics would
+/// be recognized:
+///
+/// \code
+///   int A = B; // foo-error {{use of undeclared identifier 'B'}}
+///   int C = D; // bar-error {{use of undeclared identifier 'D'}}
+/// \endcode
+///
+/// Multiple occurrences accumulate prefixes.  For example,
+/// "-verify -verify=foo,bar -verify=baz" is equivalent to
+/// "-verify=expected,foo,bar,baz".
+///
+/// SPECIFYING DIAGNOSTICS:
 ///
 /// Indicating that a line expects an error or a warning is simple. Put a
 /// comment on the line that has the diagnostic, use:
 ///
 /// \code
 ///   expected-{error,warning,remark,note}
 /// \endcode
 ///