[clang-tidy] Move clang-tidy docs to a separate directory. Create doc files for checks

The doc files for checks have been generated from the corresponding header files
using the docs/clang-tidy/tools/dump_check_docs.py script. Committing the script
as well, but the intention is to move all the user-facing docs from header files
to the rST files and add links to .h files appropriately.

llvm-svn: 246173

clang-tools-extra/docs/Doxyfile

@@ -648,7 +648,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = ../clang-modernize ../clang-apply-replacements
+INPUT                  = ../clang-modernize ../clang-apply-replacements ../clang-tidy
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is

clang-tools-extra/docs/clang-tidy/checks/google-build-explicit-make-pair.rst

@@ -0,0 +1,10 @@
+google-build-explicit-make-pair
+===============================
+
+
+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
+specified explicitly, and such use isn't intended in any case.
+
+Corresponding cpplint.py check name: 'build/explicit_make_pair'.

clang-tools-extra/docs/clang-tidy/checks/google-build-namespaces.rst

@@ -0,0 +1,9 @@
+google-build-namespaces
+=======================
+
+
+Finds anonymous namespaces in headers.
+
+http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=Namespaces#Namespaces
+
+Corresponding cpplint.py check name: 'build/namespaces'.

clang-tools-extra/docs/clang-tidy/checks/google-build-using-namespace.rst

@@ -0,0 +1,19 @@
+google-build-using-namespace
+============================
+
+
+Finds using namespace directives.
+
+http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml?showone=Namespaces#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:: c++
+
+    // Forbidden -- This pollutes the namespace.
+    using namespace foo;
+
+Corresponding cpplint.py check name: ``build/namespaces``.

clang-tools-extra/docs/clang-tidy/checks/google-explicit-constructor.rst

@@ -0,0 +1,7 @@
+google-explicit-constructor
+===========================
+
+
+Checks that all single-argument constructors are explicit.
+
+See http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Explicit_Constructors

clang-tools-extra/docs/clang-tidy/checks/google-global-names-in-headers.rst

@@ -0,0 +1,6 @@
+google-global-names-in-headers
+==============================
+
+
+Flag global namespace pollution in header files.
+Right now it only triggers on using declarations and directives.

clang-tools-extra/docs/clang-tidy/checks/google-readability-braces-around-statements.rst

@@ -0,0 +1,29 @@
+google-readability-braces-around-statements
+===========================================
+
+
+Checks that bodies of ``if`` statements and loops (``for``, ``range-for``,
+``do-while``, and ``while``) are inside braces
+
+Before:
+
+.. code:: c++
+
+  if (condition)
+    statement;
+
+After:
+
+.. code:: c++
+
+  if (condition) {
+    statement;
+  }
+
+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).

clang-tools-extra/docs/clang-tidy/checks/google-readability-casting.rst

@@ -0,0 +1,13 @@
+google-readability-casting
+==========================
+
+
+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 suggests automated fixes
+in some cases. The reported locations should not be different from the
+ones generated by ``-Wold-style-cast``.

clang-tools-extra/docs/clang-tidy/checks/google-readability-function-size.rst

@@ -0,0 +1,15 @@
+google-readability-function-size
+================================
+
+
+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).

clang-tools-extra/docs/clang-tidy/checks/google-readability-namespace-comments.rst

@@ -0,0 +1,9 @@
+google-readability-namespace-comments
+=====================================
+
+
+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

clang-tools-extra/docs/clang-tidy/checks/google-readability-redundant-smartptr-get.rst

@@ -0,0 +1,14 @@
+google-readability-redundant-smartptr-get
+=========================================
+
+
+Find and remove redundant calls to smart pointer's ``.get()`` method.
+
+Examples:
+
+.. code:: c++
+
+  ptr.get()->Foo()  ==>  ptr->Foo()
+  *ptr.get()  ==>  *ptr
+  *ptr->get()  ==>  **ptr
+

clang-tools-extra/docs/clang-tidy/checks/google-readability-todo.rst

@@ -0,0 +1,7 @@
+google-readability-todo
+=======================
+
+
+Finds TODO comments without a username or bug number.
+
+Corresponding cpplint.py check: 'readability/todo'

clang-tools-extra/docs/clang-tidy/checks/google-runtime-int.rst

@@ -0,0 +1,8 @@
+google-runtime-int
+==================
+
+
+Finds uses of ``short``, ``long`` and ``long long`` and suggest replacing them
+with ``u?intXX(_t)?``.
+
+Correspondig cpplint.py check: 'runtime/int'.

clang-tools-extra/docs/clang-tidy/checks/google-runtime-member-string-references.rst

@@ -0,0 +1,25 @@
+google-runtime-member-string-references
+=======================================
+
+
+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:: c++
+
+  struct S {
+    S(const string &Str) : Str(Str) {}
+    const string &Str;
+  };
+  S instance("string");
+
+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.
+
+Corresponding cpplint.py check name: 'runtime/member_string_reference'.

clang-tools-extra/docs/clang-tidy/checks/google-runtime-memset.rst

@@ -0,0 +1,10 @@
+google-runtime-memset
+=====================
+
+
+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.
+
+Corresponding cpplint.py check name: 'runtime/memset'.

clang-tools-extra/docs/clang-tidy/checks/google-runtime-operator.rst

@@ -0,0 +1,9 @@
+google-runtime-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'.

clang-tools-extra/docs/clang-tidy/checks/list.rst

@@ -0,0 +1,54 @@
+List of clang-tidy Checks
+=========================
+
+.. toctree::
+   google-build-explicit-make-pair
+   google-build-namespaces
+   google-build-using-namespace
+   google-explicit-constructor
+   google-global-names-in-headers
+   google-readability-braces-around-statements
+   google-readability-casting
+   google-readability-function-size
+   google-readability-namespace-comments
+   google-readability-redundant-smartptr-get
+   google-readability-todo
+   google-runtime-int
+   google-runtime-member-string-references
+   google-runtime-memset
+   google-runtime-operator
+   llvm-header-guard
+   llvm-include-order
+   llvm-namespace-comment
+   llvm-twine-local
+   misc-argument-comment
+   misc-assert-side-effect
+   misc-assign-operator-signature
+   misc-bool-pointer-implicit-conversion
+   misc-inaccurate-erase
+   misc-inefficient-algorithm
+   misc-macro-parentheses
+   misc-macro-repeated-side-effects
+   misc-move-constructor-init
+   misc-noexcept-move-constructor
+   misc-static-assert
+   misc-swapped-arguments
+   misc-undelegated-constructor
+   misc-uniqueptr-reset-release
+   misc-unused-alias-decls
+   misc-unused-parameters
+   misc-unused-raii
+   misc-use-override
+   modernize-loop-convert
+   modernize-pass-by-value
+   modernize-use-nullptr
+   readability-braces-around-statements
+   readability-container-size-empty
+   readability-else-after-return
+   readability-function-size
+   readability-identifier-naming
+   readability-named-parameter
+   readability-redundant-smartptr-get
+   readability-redundant-string-cstr
+   readability-shrink-to-fit
+   readability-simplify-boolean-expr

clang-tools-extra/docs/clang-tidy/checks/llvm-header-guard.rst

@@ -0,0 +1,4 @@
+llvm-header-guard
+=================
+
+TODO: add docs

clang-tools-extra/docs/clang-tidy/checks/llvm-include-order.rst

@@ -0,0 +1,7 @@
+llvm-include-order
+==================
+
+
+Checks the correct order of ``#includes``.
+
+See http://llvm.org/docs/CodingStandards.html#include-style

clang-tools-extra/docs/clang-tidy/checks/llvm-namespace-comment.rst

@@ -0,0 +1,9 @@
+llvm-namespace-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

clang-tools-extra/docs/clang-tidy/checks/llvm-twine-local.rst

@@ -0,0 +1,6 @@
+llvm-twine-local
+================
+
+
+Looks for local ``Twine`` variables which are prone to use after frees and
+should be generally avoided.

clang-tools-extra/docs/clang-tidy/checks/misc-argument-comment.rst

@@ -0,0 +1,18 @@
+misc-argument-comment
+=====================
+
+
+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:: c++
+
+  void f(bool foo);
+
+  ...
+  f(/*bar=*/true);
+  // warning: argument name 'bar' in comment does not match parameter name 'foo'
+
+The check tries to detect typos and suggest automated fixes for them.

clang-tools-extra/docs/clang-tidy/checks/misc-assert-side-effect.rst

@@ -0,0 +1,17 @@
+misc-assert-side-effect
+=======================
+
+
+Finds ``assert()`` with side effect.
+
+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.

clang-tools-extra/docs/clang-tidy/checks/misc-assign-operator-signature.rst

@@ -0,0 +1,10 @@
+misc-assign-operator-signature
+==============================
+
+
+Finds declarations of assign operators with the wrong return and/or argument
+types.
+
+  * The return type must be ``Class&``.
+  * Works with move-assign and assign by value.
+  * Private and deleted operators are ignored.

clang-tools-extra/docs/clang-tidy/checks/misc-bool-pointer-implicit-conversion.rst

@@ -0,0 +1,16 @@
+misc-bool-pointer-implicit-conversion
+=====================================
+
+
+Checks for conditions based on implicit conversion from a bool pointer to
+bool.
+
+Example:
+
+.. code:: c++
+
+  bool *p;
+  if (p) {
+    // Never used in a pointer-specific way.
+  }
+

clang-tools-extra/docs/clang-tidy/checks/misc-inaccurate-erase.rst

@@ -0,0 +1,11 @@
+misc-inaccurate-erase
+=====================
+
+
+Checks for inaccurate use of the ``erase()`` method.
+
+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
+``erase()`` method. This check warns when not all of the elements will be
+removed due to using an inappropriate overload.

clang-tools-extra/docs/clang-tidy/checks/misc-inefficient-algorithm.rst

@@ -0,0 +1,9 @@
+misc-inefficient-algorithm
+==========================
+
+
+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
+can take advanatage of the order of the elements.

clang-tools-extra/docs/clang-tidy/checks/misc-macro-parentheses.rst

@@ -0,0 +1,17 @@
+misc-macro-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
+unary operators may become binary operators, etc.
+
+When the replacement list has an expression, it is recommended to surround
+it with parentheses. This ensures that the macro result is evaluated
+completely before it is used.
+
+It is also recommended to surround macro arguments in the replacement list
+with parentheses. This ensures that the argument value is calculated
+properly.

clang-tools-extra/docs/clang-tidy/checks/misc-macro-repeated-side-effects.rst

@@ -0,0 +1,5 @@
+misc-macro-repeated-side-effects
+================================
+
+
+Checks for repeated argument with side effects in macros.

clang-tools-extra/docs/clang-tidy/checks/misc-move-constructor-init.rst

@@ -0,0 +1,7 @@
+misc-move-constructor-init
+==========================
+
+
+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.

clang-tools-extra/docs/clang-tidy/checks/misc-noexcept-move-constructor.rst

@@ -0,0 +1,11 @@
+misc-noexcept-move-constructor
+==============================
+
+
+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 ``noexcept``. Otherwise STL will choose copy constructors
+instead. The same is valid for move assignment operations.

clang-tools-extra/docs/clang-tidy/checks/misc-static-assert.rst

@@ -0,0 +1,9 @@
+misc-static-assert
+==================
+
+
+Replaces ``assert()`` with ``static_assert()`` if the condition is evaluatable
+at compile time.
+
+The condition of ``static_assert()`` is evaluated at compile time which is
+safer and more efficient.

clang-tools-extra/docs/clang-tidy/checks/misc-swapped-arguments.rst

@@ -0,0 +1,5 @@
+misc-swapped-arguments
+======================
+
+
+Finds potentially swapped arguments by looking at implicit conversions.

clang-tools-extra/docs/clang-tidy/checks/misc-undelegated-constructor.rst

@@ -0,0 +1,9 @@
+misc-undelegated-constructor
+============================
+
+
+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.

clang-tools-extra/docs/clang-tidy/checks/misc-uniqueptr-reset-release.rst

@@ -0,0 +1,15 @@
+misc-uniqueptr-reset-release
+============================
+
+
+Find and replace ``unique_ptr::reset(release())`` with ``std::move()``.
+
+Example:
+
+.. code:: c++
+
+  std::unique_ptr<Foo> x, y;
+  x.reset(y.release()); -> x = std::move(y);
+
+If ``y`` is already rvalue, ``std::move()`` is not added.  ``x`` and ``y`` can also
+be ``std::unique_ptr<Foo>*``.

clang-tools-extra/docs/clang-tidy/checks/misc-unused-alias-decls.rst

@@ -0,0 +1,5 @@
+misc-unused-alias-decls
+=======================
+
+
+Finds unused namespace alias declarations.

clang-tools-extra/docs/clang-tidy/checks/misc-unused-parameters.rst

@@ -0,0 +1,6 @@
+misc-unused-parameters
+======================
+
+
+Finds unused parameters and fixes them, so that ``-Wunused-parameter`` can be
+turned on.

clang-tools-extra/docs/clang-tidy/checks/misc-unused-raii.rst

@@ -0,0 +1,28 @@
+misc-unused-raii
+================
+
+
+Finds temporaries that look like RAII objects.
+
+The canonical example for this is a scoped lock.
+
+.. code:: c++
+
+  {
+    scoped_lock(&global_mutex);
+    critical_section();
+  }
+
+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
+    this.
+  * 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.

clang-tools-extra/docs/clang-tidy/checks/misc-use-override.rst

@@ -0,0 +1,5 @@
+misc-use-override
+=================
+
+
+Use C++11's ``override`` and remove ``virtual`` where applicable.

clang-tools-extra/docs/clang-tidy/checks/modernize-loop-convert.rst

@@ -0,0 +1,4 @@
+modernize-loop-convert
+======================
+
+

clang-tools-extra/docs/clang-tidy/checks/modernize-pass-by-value.rst

@@ -0,0 +1,4 @@
+modernize-pass-by-value
+=======================
+
+

clang-tools-extra/docs/clang-tidy/checks/modernize-use-nullptr.rst

@@ -0,0 +1,4 @@
+modernize-use-nullptr
+=====================
+
+

clang-tools-extra/docs/clang-tidy/checks/readability-braces-around-statements.rst

@@ -0,0 +1,29 @@
+readability-braces-around-statements
+====================================
+
+
+Checks that bodies of ``if`` statements and loops (``for``, ``range-for``,
+``do-while``, and ``while``) are inside braces
+
+Before:
+
+.. code:: c++
+
+  if (condition)
+    statement;
+
+After:
+
+.. code:: c++
+
+  if (condition) {
+    statement;
+  }
+
+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).

clang-tools-extra/docs/clang-tidy/checks/readability-container-size-empty.rst

@@ -0,0 +1,14 @@
+readability-container-size-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 ``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 ``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.

clang-tools-extra/docs/clang-tidy/checks/readability-else-after-return.rst

@@ -0,0 +1,7 @@
+readability-else-after-return
+=============================
+
+
+Flags the usages of ``else`` after ``return``.
+
+http://llvm.org/docs/CodingStandards.html#don-t-use-else-after-a-return

clang-tools-extra/docs/clang-tidy/checks/readability-function-size.rst

@@ -0,0 +1,15 @@
+readability-function-size
+=========================
+
+
+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).

clang-tools-extra/docs/clang-tidy/checks/readability-identifier-naming.rst

@@ -0,0 +1,17 @@
+readability-identifier-naming
+=============================
+
+
+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.

clang-tools-extra/docs/clang-tidy/checks/readability-named-parameter.rst

@@ -0,0 +1,15 @@
+readability-named-parameter
+===========================
+
+
+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
+implementation.
+
+Corresponding cpplint.py check name: 'readability/function'.

clang-tools-extra/docs/clang-tidy/checks/readability-redundant-smartptr-get.rst

@@ -0,0 +1,14 @@
+readability-redundant-smartptr-get
+==================================
+
+
+Find and remove redundant calls to smart pointer's ``.get()`` method.
+
+Examples:
+
+.. code:: c++
+
+  ptr.get()->Foo()  ==>  ptr->Foo()
+  *ptr.get()  ==>  *ptr
+  *ptr->get()  ==>  **ptr
+

clang-tools-extra/docs/clang-tidy/checks/readability-redundant-string-cstr.rst

@@ -0,0 +1,5 @@
+readability-redundant-string-cstr
+=================================
+
+
+Finds unnecessary calls to ``std::string::c_str()``.

clang-tools-extra/docs/clang-tidy/checks/readability-shrink-to-fit.rst

@@ -0,0 +1,10 @@
+readability-shrink-to-fit
+=========================
+
+
+Replace copy and swap tricks on shrinkable containers with the
+``shrink_to_fit()`` method call.
+
+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 ``shrink_to_fit()`` method is only available in C++11 and up.

clang-tools-extra/docs/clang-tidy/checks/readability-simplify-boolean-expr.rst

@@ -0,0 +1,76 @@
+readability-simplify-boolean-expr
+=================================
+
+
+Looks for boolean expressions involving boolean constants and simplifies
+them to use the appropriate boolean expression directly.
+
+Examples:
+
+===========================================  ================
+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``.
+
+Examples:
+  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;``.
+
+  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;``.
+
+  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);``.
+
+  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
+unchanged unless the option ``ChainedConditionalReturn`` or
+``ChainedConditionalAssignment``, respectively, is specified as non-zero.
+The default value for both options is zero.
+

clang-tools-extra/docs/clang-tidy/index.rst

@@ -2,6 +2,12 @@
 Clang-Tidy
 ==========
 
+.. toctree::
+   :maxdepth: 1
+
+   checks/list
+
+
 :program:`clang-tidy` is a clang-based C++ linter tool. Its purpose is to
 provide an extensible framework for diagnosing and fixing typical programming
 errors, like style violations, interface misuse, or bugs that can be deduced via
@@ -248,12 +254,14 @@ The Directory Structure
   |-- ClangTidyModuleRegistry.h     # Interface for registering of modules.
      ...
   |-- google/                       # Google clang-tidy module.
-  |--  |-- GoogleTidyModule.cpp
-  |--  |-- GoogleTidyModule.h
+  |-+
+    |-- GoogleTidyModule.cpp
+    |-- GoogleTidyModule.h
           ...
   |-- llvm/                         # LLVM clang-tidy module.
-  |--  |-- LLVMTidyModule.cpp
-  |--  |-- LLVMTidyModule.h
+  |-+
+    |-- LLVMTidyModule.cpp
+    |-- LLVMTidyModule.h
           ...
   |-- tool/                         # Sources of the clang-tidy binary.
           ...

clang-tools-extra/docs/clang-tidy/tools/dump_check_docs.py

@@ -0,0 +1,79 @@
+#!/usr/bin/python
+
+r"""
+Create stubs for check documentation files.
+"""
+
+import os
+import re
+import sys
+
+def main():
+  clang_tidy_dir = os.path.normpath(
+      os.path.join(os.path.dirname(sys.argv[0]), '..', '..', '..',
+                   'clang-tidy'))
+
+  checks_doc_dir = os.path.normpath(
+      os.path.join(clang_tidy_dir, '..', 'docs', 'clang-tidy', 'checks'))
+
+  registered_checks = {}
+  defined_checks = {}
+
+  for dir_name, subdir_list, file_list in os.walk(clang_tidy_dir):
+    print('Processing directory ' + dir_name + '...')
+    for file_name in file_list:
+      full_name = os.path.join(dir_name, file_name)
+      if file_name.endswith('Module.cpp'):
+        print('Module ' + file_name)
+        with open(full_name, 'r') as f:
+          text = f.read()
+        for class_name, check_name in re.findall(
+            r'\.\s*registerCheck\s*<\s*([A-Za-z0-9:]+)\s*>\(\s*"([a-z0-9-]+)"',
+            text):
+          registered_checks[check_name] = class_name
+      elif file_name.endswith('.h'):
+        print('    ' + file_name + '...')
+        with open(full_name, 'r') as f:
+          text = f.read()
+        for comment, _, _, class_name in re.findall(
+            r'((([\r\n]//)[^\r\n]*)*)\s+class (\w+)\s*:' +
+            '\s*public\s+ClangTidyCheck\s*\{', text):
+          defined_checks[class_name] = comment
+
+  print('Registered checks [%s]: [%s]' %
+        (len(registered_checks), registered_checks))
+  print('Check implementations: %s' % len(defined_checks))
+
+  checks = registered_checks.keys()
+  checks.sort()
+
+  for check_name in checks:
+    doc_file_name = os.path.join(checks_doc_dir, check_name + '.rst')
+    #if os.path.exists(doc_file_name):
+    #  print('Skipping existing file %s...')
+    #  continue
+    print('Updating %s...' % doc_file_name)
+    with open(doc_file_name, 'w') as f:
+      class_name = re.sub(r'.*:', '', registered_checks[check_name])
+      f.write(check_name + '\n' + ('=' * len(check_name)) + '\n\n')
+      if class_name in defined_checks:
+        text = defined_checks[class_name]
+        text = re.sub(r'\n//+ ?(\\brief )?', r'\n', text)
+        text = re.sub(r'(\n *)\\code\n', r'\1.. code:: c++\n\n', text)
+        text = re.sub(r'(\n *)\\endcode(\n|$)', r'\n', text)
+        text = re.sub(r'`', r'``', text)
+        f.write(text + '\n')
+      else:
+        f.write('TODO: add docs\n')
+
+  with open(os.path.join(checks_doc_dir, 'list.rst'), 'w') as f:
+    f.write(
+r"""List of clang-tidy Checks
+=========================
+
+.. toctree::
+   """ + '\n   '.join(checks))
+
+
+if __name__ == '__main__':
+  main()

clang-tools-extra/docs/index.rst

@@ -16,7 +16,7 @@ Contents
    :maxdepth: 1
 
    clang-modernize
-   clang-tidy
+   clang-tidy/index
    modularize
    pp-trace