[clang-tidy] Update docs for clang-tidy checks. NFC

Changes mostly address formatting and unification of the style. Use
MarkDown style for inline code snippets and lists. Added some text
for a few checks.

The idea is to move most of the documentation out to separate rST files and have
implementation files refer to the corresponding documentation files.

llvm-svn: 246169

clang-tools-extra/clang-tidy/google/AvoidCStyleCastsCheck.h

@@ -17,14 +17,15 @@ namespace tidy {
 namespace google {
 namespace readability {
 
-/// \brief Finds usages of C-style casts.
+/// Finds usages of C-style casts.
 ///
 /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=Casting#Casting
+///
 /// Corresponding cpplint.py check name: 'readability/casting'.
 ///
-/// This check is similar to -Wold-style-cast, but it will suggest automated
-/// fixes eventually. The reported locations should not be different from the
-/// ones generated by -Wold-style-cast.
+/// This check is similar to `-Wold-style-cast`, but it suggests automated fixes
+/// in some cases. The reported locations should not be different from the
+/// ones generated by `-Wold-style-cast`.
 class AvoidCStyleCastsCheck : public ClangTidyCheck {
 public:
   AvoidCStyleCastsCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/google/ExplicitConstructorCheck.h

@@ -16,10 +16,9 @@ namespace clang {
 namespace tidy {
 namespace google {
 
-/// \brief Checks that all single-argument constructors are explicit.
+/// Checks that all single-argument constructors are explicit.
 ///
-/// see:
-/// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Explicit_Constructors
+/// See http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Explicit_Constructors
 class ExplicitConstructorCheck : public ClangTidyCheck {
 public:
   ExplicitConstructorCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/google/ExplicitMakePairCheck.h

@@ -17,9 +17,9 @@ namespace tidy {
 namespace google {
 namespace build {
 
-/// \brief Check that make_pair's template arguments are deduced.
+/// Check that `make_pair`'s template arguments are deduced.
 ///
-/// G++ 4.6 in C++11 mode fails badly if make_pair's template arguments are
+/// G++ 4.6 in C++11 mode fails badly if `make_pair`'s template arguments are
 /// specified explicitly, and such use isn't intended in any case.
 ///
 /// Corresponding cpplint.py check name: 'build/explicit_make_pair'.

clang-tools-extra/clang-tidy/google/IntegerTypesCheck.h

@@ -17,9 +17,10 @@ namespace tidy {
 namespace google {
 namespace runtime {
 
-/// \brief Finds uses of short, long and long long and suggest replacing them
-/// with u?intXX(_t)?.
-/// Correspondig cpplint.py check: runtime/int.
+/// Finds uses of `short`, `long` and `long long` and suggest replacing them
+/// with `u?intXX(_t)?`.
+///
+/// Correspondig cpplint.py check: 'runtime/int'.
 class IntegerTypesCheck : public ClangTidyCheck {
 public:
   IntegerTypesCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/google/MemsetZeroLengthCheck.h

@@ -17,7 +17,7 @@ namespace tidy {
 namespace google {
 namespace runtime {
 
-/// \brief Finds calls to memset with a literal zero in the length argument.
+/// Finds calls to memset with a literal zero in the length argument.
 ///
 /// This is most likely unintended and the length and value arguments are
 /// swapped.

clang-tools-extra/clang-tidy/google/OverloadedUnaryAndCheck.h

@@ -17,9 +17,10 @@ namespace tidy {
 namespace google {
 namespace runtime {
 
-/// \brief Finds overloads of unary operator &.
+/// Finds overloads of unary `operator &`.
 ///
 /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=Operator_Overloading#Operator_Overloading
+///
 /// Corresponding cpplint.py check name: 'runtime/operator'.
 class OverloadedUnaryAndCheck : public ClangTidyCheck {
 public:

clang-tools-extra/clang-tidy/google/StringReferenceMemberCheck.h

@@ -17,25 +17,25 @@ namespace tidy {
 namespace google {
 namespace runtime {
 
-/// \brief Finds members of type 'const string&'.
+/// Finds members of type `const string&`.
 ///
 /// const string reference members are generally considered unsafe as they can
 /// be created from a temporary quite easily.
 ///
 /// \code
-/// struct S {
-///  S(const string &Str) : Str(Str) {}
-///  const string &Str;
-/// };
-/// S instance("string");
+///   struct S {
+///     S(const string &Str) : Str(Str) {}
+///     const string &Str;
+///   };
+///   S instance("string");
 /// \endcode
 ///
-/// In the constructor call a string temporary is created from const char * and
-/// destroyed immediately after the call. This leaves around a dangling
+/// In the constructor call a string temporary is created from `const char *`
+/// and destroyed immediately after the call. This leaves around a dangling
 /// reference.
 ///
-/// This check emit warnings for both std::string and ::string const reference
-/// members.
+/// This check emit warnings for both `std::string` and `::string` const
+/// reference members.
 ///
 /// Corresponding cpplint.py check name: 'runtime/member_string_reference'.
 class StringReferenceMemberCheck : public ClangTidyCheck {

clang-tools-extra/clang-tidy/google/TodoCommentCheck.h

@@ -17,9 +17,9 @@ namespace tidy {
 namespace google {
 namespace readability {
 
-/// \brief Finds TODO comments without a username or bug number.
+/// Finds TODO comments without a username or bug number.
 ///
-/// Corresponding cpplint.py check: readability/todo
+/// Corresponding cpplint.py check: 'readability/todo'
 class TodoCommentCheck : public ClangTidyCheck {
 public:
   TodoCommentCheck(StringRef Name, ClangTidyContext *Context);

clang-tools-extra/clang-tidy/google/UnnamedNamespaceInHeaderCheck.h

@@ -17,9 +17,10 @@ namespace tidy {
 namespace google {
 namespace build {
 
-/// \brief Finds anonymous namespaces in headers.
+/// Finds anonymous namespaces in headers.
 ///
 /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=Namespaces#Namespaces
+///
 /// Corresponding cpplint.py check name: 'build/namespaces'.
 class UnnamedNamespaceInHeaderCheck : public ClangTidyCheck {
 public:

clang-tools-extra/clang-tidy/google/UsingNamespaceDirectiveCheck.h

@@ -17,10 +17,21 @@ namespace tidy {
 namespace google {
 namespace build {
 
-/// \brief Finds using namespace directives.
+/// Finds using namespace directives.
 ///
 /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=Namespaces#Namespaces
-/// Corresponding cpplint.py check name: 'build/namespaces'.
+///
+/// The check implements the following rule of the Google C++ Style Guide:
+///
+///   You may not use a using-directive to make all names from a namespace
+///   available.
+///
+///   \code
+///     // Forbidden -- This pollutes the namespace.
+///     using namespace foo;
+///   \endcode
+///
+/// Corresponding cpplint.py check name: `build/namespaces`.
 class UsingNamespaceDirectiveCheck : public ClangTidyCheck {
 public:
   UsingNamespaceDirectiveCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/llvm/IncludeOrderCheck.h

@@ -16,9 +16,9 @@ namespace clang {
 namespace tidy {
 namespace llvm {
 
-/// \brief Checks the correct order of \c #includes.
+/// Checks the correct order of `#includes`.
 ///
-/// see: http://llvm.org/docs/CodingStandards.html#include-style
+/// See http://llvm.org/docs/CodingStandards.html#include-style
 class IncludeOrderCheck : public ClangTidyCheck {
 public:
   IncludeOrderCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/llvm/TwineLocalCheck.h

@@ -16,8 +16,8 @@ namespace clang {
 namespace tidy {
 namespace llvm {
 
-/// \brief Looks for local Twine variables which are prone to use after frees
-/// and should be generally avoided.
+/// Looks for local `Twine` variables which are prone to use after frees and
+/// should be generally avoided.
 class TwineLocalCheck : public ClangTidyCheck {
 public:
   TwineLocalCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/misc/ArgumentCommentCheck.h

@@ -17,7 +17,20 @@ namespace clang {
 namespace tidy {
 namespace misc {
 
-/// \brief Checks that argument comments match parameter names.
+/// Checks that argument comments match parameter names.
+///
+/// The check understands argument comments in the form `/*parameter_name=*/`
+/// that are placed right before the argument.
+///
+/// \code
+///   void f(bool foo);
+///
+///   ...
+///   f(/*bar=*/true);
+///   // warning: argument name 'bar' in comment does not match parameter name 'foo'
+/// \endcode
+///
+/// The check tries to detect typos and suggest automated fixes for them.
 class ArgumentCommentCheck : public ClangTidyCheck {
 public:
   ArgumentCommentCheck(StringRef Name, ClangTidyContext *Context);

clang-tools-extra/clang-tidy/misc/AssertSideEffectCheck.h

@@ -18,19 +18,19 @@
 namespace clang {
 namespace tidy {
 
-/// \brief Finds \c assert() with side effect.
+/// Finds `assert()` with side effect.
 ///
-/// The condition of \c assert() is evaluated only in debug builds so a
+/// The condition of `assert()` is evaluated only in debug builds so a
 /// condition with side effect can cause different behavior in debug / release
 /// builds.
 ///
 /// There are two options:
-/// - AssertMacros: A comma-separated list of the names of assert macros to be
-///   checked.
-/// - CheckFunctionCalls: Whether to treat non-const member and non-member
-///   functions as they produce side effects. Disabled by default because it can
-///   increase the number of false positive warnings.
-
+///
+///   - `AssertMacros`: A comma-separated list of the names of assert macros to
+///     be checked.
+///   - `CheckFunctionCalls`: Whether to treat non-const member and non-member
+///     functions as they produce side effects. Disabled by default because it
+///     can increase the number of false positive warnings.
 class AssertSideEffectCheck : public ClangTidyCheck {
 public:
   AssertSideEffectCheck(StringRef Name, ClangTidyContext *Context);

clang-tools-extra/clang-tidy/misc/AssignOperatorSignatureCheck.h

@@ -16,12 +16,12 @@ namespace clang {
 namespace tidy {
 namespace misc {
 
-/// \brief Finds declarations of assign operators with the wrong return and/or
-///   argument types.
+/// Finds declarations of assign operators with the wrong return and/or argument
+/// types.
 ///
-/// The return type must be \c Class&.
-/// Works with move-assign and assign by value.
-/// Private and deleted operators are ignored.
+///   * The return type must be `Class&`.
+///   * Works with move-assign and assign by value.
+///   * Private and deleted operators are ignored.
 class AssignOperatorSignatureCheck : public ClangTidyCheck {
 public:
   AssignOperatorSignatureCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/misc/BoolPointerImplicitConversionCheck.h

@@ -16,12 +16,17 @@ namespace clang {
 namespace tidy {
 namespace misc {
 
-/// \brief Checks for conditions based on implicit conversion from a bool
-/// pointer to bool e.g.
-/// bool *p;
-/// if (p) {
-///   // Never used in a pointer-specific way.
-/// }
+/// Checks for conditions based on implicit conversion from a bool pointer to
+/// bool.
+///
+/// Example:
+///
+/// \code
+///   bool *p;
+///   if (p) {
+///     // Never used in a pointer-specific way.
+///   }
+/// \endcode
 class BoolPointerImplicitConversionCheck : public ClangTidyCheck {
 public:
   BoolPointerImplicitConversionCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/misc/InaccurateEraseCheck.h

@@ -16,12 +16,12 @@ namespace clang {
 namespace tidy {
 namespace misc {
 
-/// \brief Checks for inaccurate use of \c erase() method.
+/// Checks for inaccurate use of the `erase()` method.
 ///
-/// Algorithms like \c remove() do not actually remove any element from the
+/// Algorithms like `remove()` do not actually remove any element from the
 /// container but return an iterator to the first redundant element at the end
 /// of the container. These redundant elements must be removed using the
-/// \c erase() method. This check warns when not all of the elements will be
+/// `erase()` method. This check warns when not all of the elements will be
 /// removed due to using an inappropriate overload.
 class InaccurateEraseCheck : public ClangTidyCheck {
 public:

clang-tools-extra/clang-tidy/misc/InefficientAlgorithmCheck.h

@@ -16,7 +16,7 @@ namespace clang {
 namespace tidy {
 namespace misc {
 
-/// \brief Warns on inefficient use of STL algorithms on associative containers.
+/// Warns on inefficient use of STL algorithms on associative containers.
 ///
 /// Associative containers implements some of the algorithms as methods which
 /// should be preferred to the algorithms in the algorithm header. The methods

clang-tools-extra/clang-tidy/misc/MacroParenthesesCheck.cpp

@@ -54,14 +54,14 @@ static bool isSurroundedRight(const Token &T) {
 
 /// Is given TokenKind a keyword?
 static bool isKeyword(const Token &T) {
-  /// \TODO better matching of keywords to avoid false positives
+  // FIXME: better matching of keywords to avoid false positives.
   return T.isOneOf(tok::kw_case, tok::kw_const, tok::kw_struct);
 }
 
 /// Warning is written when one of these operators are not within parentheses.
 static bool isWarnOp(const Token &T) {
-  /// \TODO This is an initial list of operators. It can be tweaked later to
-  /// get more positives or perhaps avoid some false positive.
+  // FIXME: This is an initial list of operators. It can be tweaked later to
+  // get more positives or perhaps avoid some false positive.
   return T.isOneOf(tok::plus, tok::minus, tok::star, tok::slash, tok::percent,
                    tok::amp, tok::pipe, tok::caret);
 }

clang-tools-extra/clang-tidy/misc/MacroParenthesesCheck.h

@@ -15,8 +15,7 @@
 namespace clang {
 namespace tidy {
 
-/// \brief Finds macros that can have unexpected behaviour due to missing
-/// parentheses.
+/// Finds macros that can have unexpected behaviour due to missing parentheses.
 ///
 /// Macros are expanded by the preprocessor as-is. As a result, there can be
 /// unexpected behaviour; operators may be evaluated in unexpected order and

clang-tools-extra/clang-tidy/misc/MacroRepeatedSideEffectsCheck.h

@@ -16,8 +16,7 @@ namespace clang {
 namespace tidy {
 namespace misc {
 
-/// \brief Checks for repeated argument with side effects in macros.
-///
+/// Checks for repeated argument with side effects in macros.
 class MacroRepeatedSideEffectsCheck : public ClangTidyCheck {
 public:
   MacroRepeatedSideEffectsCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/misc/MoveConstructorInitCheck.h

@@ -15,9 +15,9 @@
 namespace clang {
 namespace tidy {
 
-/// \brief The check flags user-defined move constructors that have a
-/// ctor-initializer initializing a member or base class through a copy
-/// constructor instead of a move constructor.
+/// The check flags user-defined move constructors that have a ctor-initializer
+/// initializing a member or base class through a copy constructor instead of a
+/// move constructor.
 class MoveConstructorInitCheck : public ClangTidyCheck {
 public:
   MoveConstructorInitCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/misc/NoexceptMoveConstructorCheck.h

@@ -15,12 +15,12 @@
 namespace clang {
 namespace tidy {
 
-/// \brief The check flags user-defined move constructors and assignment
-/// operators not marked with \c noexcept or marked with \c noexcept(expr) where
-/// \c expr evaluates to \c false (but is not a \c false literal itself).
+/// The check flags user-defined move constructors and assignment operators not
+/// marked with `noexcept` or marked with `noexcept(expr)` where `expr`
+/// evaluates to `false` (but is not a `false` literal itself).
 ///
 /// Move constructors of all the types used with STL containers, for example,
-/// need to be declared \c noexcept. Otherwise STL will choose copy constructors
+/// need to be declared `noexcept`. Otherwise STL will choose copy constructors
 /// instead. The same is valid for move assignment operations.
 class NoexceptMoveConstructorCheck : public ClangTidyCheck {
 public:

clang-tools-extra/clang-tidy/misc/StaticAssertCheck.h

@@ -17,10 +17,10 @@
 namespace clang {
 namespace tidy {
 
-/// \brief Replaces \c assert() with \c static_assert() if the condition is
-/// evaluatable at compile time.
+/// Replaces `assert()` with `static_assert()` if the condition is evaluatable
+/// at compile time.
 ///
-/// The condition of \c static_assert() is evaluated at compile time which is
+/// The condition of `static_assert()` is evaluated at compile time which is
 /// safer and more efficient.
 class StaticAssertCheck : public ClangTidyCheck {
 public:

clang-tools-extra/clang-tidy/misc/SwappedArgumentsCheck.h

@@ -16,8 +16,7 @@ namespace clang {
 namespace tidy {
 namespace misc {
 
-/// \brief Finds potentially swapped arguments by looking at implicit
-/// conversions.
+/// Finds potentially swapped arguments by looking at implicit conversions.
 class SwappedArgumentsCheck : public ClangTidyCheck {
 public:
   SwappedArgumentsCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/misc/UndelegatedConstructor.h

@@ -16,9 +16,11 @@ namespace clang {
 namespace tidy {
 namespace misc {
 
-/// \brief Finds creation of temporary objects in constructors that look like a
-/// function call to another constructor of the same class. The user most likely
-/// meant to use a delegating constructor or base class initializer.
+/// Finds creation of temporary objects in constructors that look like a
+/// function call to another constructor of the same class.
+///
+/// The user most likely meant to use a delegating constructor or base class
+/// initializer.
 class UndelegatedConstructorCheck : public ClangTidyCheck {
 public:
   UndelegatedConstructorCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/misc/UniqueptrResetReleaseCheck.h

@@ -16,14 +16,17 @@ namespace clang {
 namespace tidy {
 namespace misc {
 
-/// \brief Find and replace unique_ptr::reset(release()) with std::move
+/// Find and replace `unique_ptr::reset(release())` with `std::move()`.
 ///
 /// Example:
+///
+/// \code
 ///   std::unique_ptr<Foo> x, y;
 ///   x.reset(y.release()); -> x = std::move(y);
+/// \endcode
 ///
-/// If "y" is already rvalue, std::move is not added.
-/// "x" and "y" can also be std::unique_ptr<Foo>*.
+/// If `y` is already rvalue, `std::move()` is not added.  `x` and `y` can also
+/// be `std::unique_ptr<Foo>*`.
 class UniqueptrResetReleaseCheck : public ClangTidyCheck {
 public:
   UniqueptrResetReleaseCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/misc/UnusedAliasDeclsCheck.h

@@ -15,7 +15,7 @@
 namespace clang {
 namespace tidy {
 
-/// \brief Finds unused namespace alias declarations.
+/// Finds unused namespace alias declarations.
 class UnusedAliasDeclsCheck : public ClangTidyCheck {
 public:
   UnusedAliasDeclsCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/misc/UnusedParametersCheck.h

@@ -15,8 +15,8 @@
 namespace clang {
 namespace tidy {
 
-/// \brief Finds unused parameters and fixes them, so that -Wunused-parameter
-/// can be turned on.
+/// Finds unused parameters and fixes them, so that `-Wunused-parameter` can be
+/// turned on.
 class UnusedParametersCheck : public ClangTidyCheck {
 public:
   UnusedParametersCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/misc/UnusedRAIICheck.h

@@ -16,26 +16,30 @@ namespace clang {
 namespace tidy {
 namespace misc {
 
-/// \brief Finds temporaries that look like RAII objects.
+/// Finds temporaries that look like RAII objects.
 ///
 /// The canonical example for this is a scoped lock.
+///
 /// \code
 ///   {
 ///     scoped_lock(&global_mutex);
 ///     critical_section();
 ///   }
 /// \endcode
-/// The destructor of the scoped_lock is called before the critical_section is
+///
+/// The destructor of the scoped_lock is called before the `critical_section` is
 /// entered, leaving it unprotected.
 ///
 /// We apply a number of heuristics to reduce the false positive count of this
 /// check:
-///   - Ignore code expanded from macros. Testing frameworks make heavy use of
+///
+///   * Ignore code expanded from macros. Testing frameworks make heavy use of
 ///     this.
-///   - Ignore types with no user-declared constructor. Those are very unlikely
+///   * Ignore types with no user-declared constructor. Those are very unlikely
 ///     to be RAII objects.
-///   - Ignore objects at the end of a compound statement (doesn't change behavior).
-///   - Ignore objects returned from a call.
+///   * Ignore objects at the end of a compound statement (doesn't change
+///     behavior).
+///   * Ignore objects returned from a call.
 class UnusedRAIICheck : public ClangTidyCheck {
 public:
   UnusedRAIICheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/misc/UseOverrideCheck.h

@@ -16,7 +16,7 @@ namespace clang {
 namespace tidy {
 namespace misc {
 
-/// \brief Use C++11's 'override' and remove 'virtual' where applicable.
+/// Use C++11's `override` and remove `virtual` where applicable.
 class UseOverrideCheck : public ClangTidyCheck {
 public:
   UseOverrideCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/readability/BracesAroundStatementsCheck.h

@@ -16,25 +16,31 @@ namespace clang {
 namespace tidy {
 namespace readability {
 
-/// \brief Checks that bodies of 'if' statements and loops ('for', 'range-for',
-/// 'do-while', and 'while') are inside braces
+/// Checks that bodies of `if` statements and loops (`for`, `range-for`,
+/// `do-while`, and `while`) are inside braces
 ///
 /// Before:
-/// if (condition)
-///   statement;
+///
+/// \code
+///   if (condition)
+///     statement;
+/// \endcode
 ///
 /// After:
-/// if (condition) {
-///   statement;
-/// }
+///
+/// \code
+///   if (condition) {
+///     statement;
+///   }
+/// \endcode
 ///
 /// Additionally, one can define an option `ShortStatementLines` defining the
 /// minimal number of lines that the statement should have in order to trigger
 /// this check.
+///
 /// The number of lines is counted from the end of condition or initial keyword
-/// (do/else) until the last line of the inner statement.
-/// Default value 0 means that braces will be added to all statements (not
-/// having them already).
+/// (`do`/`else`) until the last line of the inner statement.  Default value 0
+/// means that braces will be added to all statements (not having them already).
 class BracesAroundStatementsCheck : public ClangTidyCheck {
 public:
   BracesAroundStatementsCheck(StringRef Name, ClangTidyContext *Context);

clang-tools-extra/clang-tidy/readability/ContainerSizeEmptyCheck.h

@@ -16,16 +16,16 @@ namespace clang {
 namespace tidy {
 namespace readability {
 
-/// \brief Checks whether a call to the \c size() method can be replaced with a
-/// call to \c empty().
+/// Checks whether a call to the `size()` method can be replaced with a call to
+/// `empty()`.
 ///
-/// The emptiness of a container should be checked using the \c empty() method
-/// instead of the \c size() method. It is not guaranteed that \c size() is a
+/// The emptiness of a container should be checked using the `empty()` method
+/// instead of the `size()` method. It is not guaranteed that `size()` is a
 /// constant-time function, and it is generally more efficient and also shows
-/// clearer intent to use \c empty(). Furthermore some containers may implement
-/// the \c empty() method but not implement the \c size() method. Using \c
-/// empty() whenever possible makes it easier to switch to another container in
-/// the future.
+/// clearer intent to use `empty()`. Furthermore some containers may implement
+/// the `empty()` method but not implement the `size()` method. Using `empty()`
+/// whenever possible makes it easier to switch to another container in the
+/// future.
 class ContainerSizeEmptyCheck : public ClangTidyCheck {
 public:
   ContainerSizeEmptyCheck(StringRef Name, ClangTidyContext *Context);

clang-tools-extra/clang-tidy/readability/ElseAfterReturnCheck.h

@@ -16,6 +16,9 @@ namespace clang {
 namespace tidy {
 namespace readability {
 
+/// Flags the usages of `else` after `return`.
+///
+/// http://llvm.org/docs/CodingStandards.html#don-t-use-else-after-a-return
 class ElseAfterReturnCheck : public ClangTidyCheck {
 public:
   ElseAfterReturnCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/readability/FunctionSizeCheck.h

@@ -16,7 +16,17 @@ namespace clang {
 namespace tidy {
 namespace readability {
 
-/// \brief Checks for large functions based on various metrics.
+/// Checks for large functions based on various metrics.
+///
+/// These options are supported:
+///
+///   * `LineThreshold` - flag functions exceeding this number of lines. The
+///     default is `-1` (ignore the number of lines).
+///   * `StatementThreshold` - flag functions exceeding this number of
+///     statements. This may differ significantly from the number of lines for
+///     macro-heavy code. The default is `800`.
+///   * `BranchThreshold` - flag functions exceeding this number of control
+///     statements. The default is `-1` (ignore the number of branches).
 class FunctionSizeCheck : public ClangTidyCheck {
 public:
   FunctionSizeCheck(StringRef Name, ClangTidyContext *Context);

clang-tools-extra/clang-tidy/readability/IdentifierNamingCheck.h

@@ -16,7 +16,19 @@ namespace clang {
 namespace tidy {
 namespace readability {
 
-/// \brief Checks for identifiers naming style mismatch.
+/// Checks for identifiers naming style mismatch.
+///
+/// This check will try to enforce coding guidelines on the identifiers naming.
+/// It supports `lower_case`, `UPPER_CASE`, `camelBack` and `CamelCase` casing
+/// and tries to convert from one to another if a mismatch is detected.
+///
+/// It also supports a fixed prefix and suffix that will be prepended or
+/// appended to the identifiers, regardless of the casing.
+///
+/// Many configuration options are available, in order to be able to create
+/// different rules for different kind of identifier. In general, the
+/// rules are falling back to a more generic rule if the specific case is not
+/// configured.
 class IdentifierNamingCheck : public ClangTidyCheck {
 public:
   IdentifierNamingCheck(StringRef Name, ClangTidyContext *Context);

clang-tools-extra/clang-tidy/readability/NamedParameterCheck.h

@@ -16,10 +16,11 @@ namespace clang {
 namespace tidy {
 namespace readability {
 
-/// \brief Find functions with unnamed arguments.
+/// Find functions with unnamed arguments.
 ///
 /// The check implements the following rule originating in the Google C++ Style
 /// Guide:
+///
 /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=Function_Declarations_and_Definitions#Function_Declarations_and_Definitions
 ///
 /// All parameters should be named, with identical names in the declaration and

clang-tools-extra/clang-tidy/readability/NamespaceCommentCheck.h

@@ -17,9 +17,10 @@ namespace clang {
 namespace tidy {
 namespace readability {
 
-/// \brief Checks that long namespaces have a closing comment.
+/// Checks that long namespaces have a closing comment.
 ///
 /// http://llvm.org/docs/CodingStandards.html#namespace-indentation
+///
 /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.html#Namespaces
 class NamespaceCommentCheck : public ClangTidyCheck {
 public:

clang-tools-extra/clang-tidy/readability/RedundantSmartptrGetCheck.h

@@ -16,12 +16,15 @@ namespace clang {
 namespace tidy {
 namespace readability {
 
-/// \brief Find and remove redundant calls to smart pointer's .get() method.
+/// Find and remove redundant calls to smart pointer's `.get()` method.
 ///
 /// Examples:
+///
+/// \code
 ///   ptr.get()->Foo()  ==>  ptr->Foo()
 ///   *ptr.get()  ==>  *ptr
 ///   *ptr->get()  ==>  **ptr
+/// \endcode
 class RedundantSmartptrGetCheck : public ClangTidyCheck {
 public:
   RedundantSmartptrGetCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/readability/RedundantStringCStrCheck.h

@@ -16,7 +16,7 @@ namespace clang {
 namespace tidy {
 namespace readability {
 
-/// \brief Finds unnecessary calls to std::string::c_str().
+/// Finds unnecessary calls to `std::string::c_str()`.
 class RedundantStringCStrCheck : public ClangTidyCheck {
 public:
   RedundantStringCStrCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/readability/ShrinkToFitCheck.h

@@ -16,12 +16,12 @@ namespace clang {
 namespace tidy {
 namespace readability {
 
-/// \brief Replace copy and swap tricks on shrinkable containers with the
-/// \c shrink_to_fit() method call.
+/// Replace copy and swap tricks on shrinkable containers with the
+/// `shrink_to_fit()` method call.
 ///
-/// The \c shrink_to_fit() method is more readable and more effective than
+/// The `shrink_to_fit()` method is more readable and more effective than
 /// the copy and swap trick to reduce the capacity of a shrinkable container.
-/// Note that, the \c shrink_to_fit() method is only available in C++11 and up.
+/// Note that, the `shrink_to_fit()` method is only available in C++11 and up.
 class ShrinkToFitCheck : public ClangTidyCheck {
 public:
   ShrinkToFitCheck(StringRef Name, ClangTidyContext *Context)

clang-tools-extra/clang-tidy/readability/SimplifyBooleanExprCheck.h

@@ -16,64 +16,71 @@ namespace clang {
 namespace tidy {
 namespace readability {
 
-/// \brief Looks for boolean expressions involving boolean constants and
-// simplifies them to use the appropriate boolean expression directly.
+/// Looks for boolean expressions involving boolean constants and simplifies
+/// them to use the appropriate boolean expression directly.
 ///
 /// Examples:
-/// `if (b == true)`                           becomes `if (b)`
-/// `if (b == false)`                          becomes `if (!b)`
-/// `if (b && true)`                           becomes `if (b)`
-/// `if (b && false)`                          becomes `if (false)`
-/// `if (b || true)`                           becomes `if (true)`
-/// `if (b || false)`                          becomes `if (b)`
-/// `e ? true : false`                         becomes `e`
-/// `e ? false : true`                         becomes `!e`
-/// `if (true) t(); else f();`                 becomes `t();`
-/// `if (false) t(); else f();`                becomes `f();`
-/// `if (e) return true; else return false;`   becomes `return e;`
-/// `if (e) return false; else return true;`   becomes `return !e;`
-/// `if (e) b = true; else b = false;`         becomes `b = e;`
-/// `if (e) b = false; else b = true;`         becomes `b = !e;`
-/// `if (e) return true; return false;`        becomes `return e;`
-/// `if (e) return false; return true;`        becomes `return !e;`
+///
+/// ===========================================  ================
+/// Initial expression                           Result
+/// -------------------------------------------  ----------------
+/// `if (b == true)`                             `if (b)`
+/// `if (b == false)`                            `if (!b)`
+/// `if (b && true)`                             `if (b)`
+/// `if (b && false)`                            `if (false)`
+/// `if (b || true)`                             `if (true)`
+/// `if (b || false)`                            `if (b)`
+/// `e ? true : false`                           `e`
+/// `e ? false : true`                           `!e`
+/// `if (true) t(); else f();`                   `t();`
+/// `if (false) t(); else f();`                  `f();`
+/// `if (e) return true; else return false;`     `return e;`
+/// `if (e) return false; else return true;`     `return !e;`
+/// `if (e) b = true; else b = false;`           `b = e;`
+/// `if (e) b = false; else b = true;`           `b = !e;`
+/// `if (e) return true; return false;`          `return e;`
+/// `if (e) return false; return true;`          `return !e;`
+/// ===========================================  ================
 ///
 /// The resulting expression `e` is modified as follows:
-/// 1. Unnecessary parentheses around the expression are removed.
-/// 2. Negated applications of `!` are eliminated.
-/// 3. Negated applications of comparison operators are changed to use the
-///    opposite condition.
-/// 4. Implicit conversions of pointer to `bool` are replaced with explicit
-///    comparisons to `nullptr`.
-/// 5. Implicit casts to `bool` are replaced with explicit casts to `bool`.
-/// 6. Object expressions with `explicit operator bool` conversion operators
-///    are replaced with explicit casts to `bool`.
+///   1. Unnecessary parentheses around the expression are removed.
+///   2. Negated applications of `!` are eliminated.
+///   3. Negated applications of comparison operators are changed to use the
+///      opposite condition.
+///   4. Implicit conversions of pointer to `bool` are replaced with explicit
+///      comparisons to `nullptr`.
+///   5. Implicit casts to `bool` are replaced with explicit casts to `bool`.
+///   6. Object expressions with `explicit operator bool` conversion operators
+///      are replaced with explicit casts to `bool`.
 ///
 /// Examples:
-/// 1. The ternary assignment `bool b = (i < 0) ? true : false;` has redundant
-/// parentheses and becomes `bool b = i < 0;`.
+///   1. The ternary assignment `bool b = (i < 0) ? true : false;` has redundant
+///      parentheses and becomes `bool b = i < 0;`.
 ///
-/// 2. The conditional return `if (!b) return false; return true;` has an
-/// implied double negation and becomes `return b;`.
+///   2. The conditional return `if (!b) return false; return true;` has an
+///      implied double negation and becomes `return b;`.
 ///
-/// 3. The conditional return `if (i < 0) return false; return true;` becomes
-/// `return i >= 0;`.
-/// The conditional return `if (i != 0) return false; return true;` becomes
-/// `return i == 0;`.
+///   3. The conditional return `if (i < 0) return false; return true;` becomes
+///      `return i >= 0;`.
 ///
-/// 4. The conditional return `if (p) return true; return false;` has an
-/// implicit conversion of a pointer to `bool` and becomes
-/// `return p != nullptr;`.
-/// The ternary assignment `bool b = (i & 1) ? true : false;` has an implicit
-/// conversion of `i & 1` to `bool` and becomes
-/// `bool b = static_cast<bool>(i & 1);`.
+///      The conditional return `if (i != 0) return false; return true;` becomes
+///      `return i == 0;`.
 ///
-/// 5. The conditional return `if (i & 1) return true; else return false;` has
-/// an implicit conversion of an integer quantity `i & 1` to `bool` and becomes
-/// `return static_cast<bool>(i & 1);`
+///   4. The conditional return `if (p) return true; return false;` has an
+///      implicit conversion of a pointer to `bool` and becomes
+///      `return p != nullptr;`.
 ///
-/// 6. Given `struct X { explicit operator bool(); };`, and an instance `x` of
-/// `struct X`, the conditional return `if (x) return true; return false;`
-/// becomes `return static_cast<bool>(x);`
+///      The ternary assignment `bool b = (i & 1) ? true : false;` has an
+///      implicit conversion of `i & 1` to `bool` and becomes
+///      `bool b = static_cast<bool>(i & 1);`.
+///
+///   5. The conditional return `if (i & 1) return true; else return false;` has
+///      an implicit conversion of an integer quantity `i & 1` to `bool` and
+///      becomes `return static_cast<bool>(i & 1);`
+///
+///   6. Given `struct X { explicit operator bool(); };`, and an instance `x` of
+///      `struct X`, the conditional return `if (x) return true; return false;`
+///      becomes `return static_cast<bool>(x);`
 ///
 /// When a conditional boolean return or assignment appears at the end of a
 /// chain of `if`, `else if` statements, the conditional statement is left

clang-tools-extra/clang-tidy/utils/HeaderGuard.h

@@ -15,7 +15,7 @@
 namespace clang {
 namespace tidy {
 
-/// \brief Finds and fixes header guards.
+/// Finds and fixes header guards.
 class HeaderGuardCheck : public ClangTidyCheck {
 public:
   HeaderGuardCheck(StringRef Name, ClangTidyContext *Context)