[Clang-tidy] Improve checks documentation consistency

[Eugene.Zelenko]

Summary

I tried to make using of ` and more consistent. Two Google checks changed to aliases.

I'm not sure about using :option: for check options.

[alexfh]

Awesome! Thanks!

[alexfh]

Also, could you, please, next time generate diffs with full context as documented in http://llvm.org/docs/Phabricator.html#requesting-a-review-via-the-web-interface (or use arcanist, which does this automatically)? This sometimes (not in this case) saves reviewers manual work of finding the relevant source files and looking into them in order to see the context. Thanks!

[Eugene.Zelenko]

In D18717#390151, @alexfh wrote:

Also, could you, please, next time generate diffs with full context as documented in http://llvm.org/docs/Phabricator.html#requesting-a-review-via-the-web-interface (or use arcanist, which does this automatically)? This sometimes (not in this case) saves reviewers manual work of finding the relevant source files and looking into them in order to see the context. Thanks!

I'll try to not forget next time :-)

clang-tools-extra/trunk/docs/clang-tidy/checks/cert-err52-cpp.rst

 .. title:: clang-tidy - cert-err52-cpp
 
 cert-err52-cpp
 ==============
 
-This check flags all call expressions involving setjmp() and longjmp().
+This check flags all call expressions involving ``setjmp()`` and ``longjmp()``.
 
 This check corresponds to the CERT C++ Coding Standard rule
 `ERR52-CPP. Do not use setjmp() or longjmp()
 <https://www.securecoding.cert.org/confluence/pages/viewpage.action?pageId=1834>`_.

clang-tools-extra/trunk/docs/clang-tidy/checks/cert-err58-cpp.rst

 .. title:: clang-tidy - cert-err58-cpp
 
 cert-err58-cpp
 ==============
 
-This check flags all static or thread_local variable declarations where the
-constructor for the object may throw an exception.
+This check flags all ``static`` or ``thread_local`` variable declarations where
+the constructor for the object may throw an exception.
 
 This check corresponds to the CERT C++ Coding Standard rule
 `ERR58-CPP. Constructors of objects with static or thread storage duration must not throw exceptions
 <https://www.securecoding.cert.org/confluence/display/cplusplus/ERR58-CPP.+Constructors+of+objects+with+static+or+thread+storage+duration+must+not+throw+exceptions>`_.

clang-tools-extra/trunk/docs/clang-tidy/checks/cert-flp30-c.rst

 .. title:: clang-tidy - cert-flp30-c
 
 cert-flp30-c
 ============
 
-This check flags ``for`` loops where the induction expression has a floating-
-point type.
+This check flags ``for`` loops where the induction expression has a
+floating-point type.
 
 This check corresponds to the CERT C Coding Standard rule
 `FLP30-C. Do not use floating-point variables as loop counters
 <https://www.securecoding.cert.org/confluence/display/c/FLP30-C.+Do+not+use+floating-point+variables+as+loop+counters>`_.

clang-tools-extra/trunk/docs/clang-tidy/checks/cppcoreguidelines-pro-bounds-constant-array-index.rst

 .. title:: clang-tidy - cppcoreguidelines-pro-bounds-constant-array-index
 
 cppcoreguidelines-pro-bounds-constant-array-index
 =================================================
 
 This check flags all array subscript expressions on static arrays and
 ``std::arrays`` that either do not have a constant integer expression index or
 are out of bounds (for ``std::array``). For out-of-bounds checking of static
 arrays, see the clang-diagnostic-array-bounds check.
 
-The check can generate fixes after the option
-``cppcoreguidelines-pro-bounds-constant-array-index.GslHeader`` has been set to
-the name of the include file that contains ``gsl::at()``, e.g. ``"gsl/gsl.h"``.
+The check can generate fixes after the option :option:`GslHeader` has been set
+to the name of the include file that contains ``gsl::at()``, e.g. `"gsl/gsl.h"`.
 
 This rule is part of the "Bounds safety" profile of the C++ Core Guidelines, see
 https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-bounds-arrayindex.

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

 .. title:: clang-tidy - google-build-explicit-make-pair
 
 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'.
+Corresponding cpplint.py check name: `build/explicit_make_pair`.

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

 .. title:: clang-tidy - google-build-namespaces
 
 google-build-namespaces
 =======================
 
-"cert-dcl59-cpp" redirects here as an alias for this check.
+`cert-dcl59-cpp` redirects here as an alias for this check.
 
 Finds anonymous namespaces in headers.
 
 https://google.github.io/styleguide/cppguide.html#Namespaces
 
-Corresponding cpplint.py check name: 'build/namespaces'.
+Corresponding cpplint.py check name: `build/namespaces`.

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

 .. title:: clang-tidy - google-build-using-namespace
 
 google-build-using-namespace
 ============================
 
-
-Finds using namespace directives.
+Finds ``using namespace`` directives.
 
 https://google.github.io/styleguide/cppguide.html#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``.
+Corresponding cpplint.py check name: `build/namespaces`.

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

 .. title:: clang-tidy - google-global-names-in-headers
 
 google-global-names-in-headers
 ==============================
 
-
 Flag global namespace pollution in header files.
-Right now it only triggers on using declarations and directives.
+Right now it only triggers on ``using`` declarations and directives.

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

 .. title:: clang-tidy - google-readability-braces-around-statements
+.. meta::
+   :http-equiv=refresh: 5;URL=readability-braces-around-statements.html
 
 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).
+The google-readability-braces-around-statements check is an alias, please see
+`readability-braces-around-statements <readability-braces-around-statements.html>`_
+for more information.

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

 .. title:: clang-tidy - google-readability-casting
 
 google-readability-casting
 ==========================
 
-
 Finds usages of C-style casts.
 
 https://google.github.io/styleguide/cppguide.html#Casting
 
-Corresponding cpplint.py check name: 'readability/casting'.
+Corresponding cpplint.py check name: `readability/casting`.
 
-This check is similar to ``-Wold-style-cast``, but it suggests automated fixes
+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``.
+ones generated by `-Wold-style-cast`.

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

 .. title:: clang-tidy - google-readability-function-size
+.. meta::
+   :http-equiv=refresh: 5;URL=readability-function-size.html
 
 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).
+The google-readability-function-size check is an alias, please see
+`readability-function-size <readability-function-size.html>`_ for more
+information.

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

 .. title:: clang-tidy - google-readability-todo
 
 google-readability-todo
 =======================
 
-
 Finds TODO comments without a username or bug number.
 
-Corresponding cpplint.py check: 'readability/todo'
+Corresponding cpplint.py check: `readability/todo`

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

 .. title:: clang-tidy - google-runtime-int
 
 google-runtime-int
 ==================
 
-
 Finds uses of ``short``, ``long`` and ``long long`` and suggest replacing them
 with ``u?intXX(_t)?``.
 
 The corresponding style guide rule:
 https://google-styleguide.googlecode.com/svn/trunk/cppguide.html#Integer_Types.
 
-Correspondig cpplint.py check: 'runtime/int'.
+Correspondig cpplint.py check: `runtime/int`.

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

 .. title:: clang-tidy - google-runtime-member-string-references
 
 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'.
+Corresponding cpplint.py check name: `runtime/member_string_reference`.

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

 .. title:: clang-tidy - google-runtime-memset
 
 google-runtime-memset
 =====================
 
+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.
 
-This is most likely unintended and the length and value arguments are
-swapped.
-
-Corresponding cpplint.py check name: 'runtime/memset'.
+Corresponding cpplint.py check name: `runtime/memset`.

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

 .. title:: clang-tidy - google-runtime-operator
 
 google-runtime-operator
 =======================
 
-
 Finds overloads of unary ``operator &``.
 
 https://google.github.io/styleguide/cppguide.html#Operator_Overloading
 
-Corresponding cpplint.py check name: 'runtime/operator'.
+Corresponding cpplint.py check name: `runtime/operator`.

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

.. toctree::
    cppcoreguidelines-pro-type-static-cast-downcast
    cppcoreguidelines-pro-type-union-access
    cppcoreguidelines-pro-type-vararg
    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-braces-around-statements (redirects to readability-braces-around-statements) <readability-braces-around-statements>
    google-readability-casting
-   google-readability-function-size
+   google-readability-function-size (redirects to readability-function-size) <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
    google-runtime-references

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

 .. title:: clang-tidy - misc-assert-side-effect
 
 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.
+  - :option:`AssertMacros`: A comma-separated list of the names of assert macros
+    to be checked.
+  - :option:`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/trunk/docs/clang-tidy/checks/misc-bool-pointer-implicit-conversion.rst

 .. title:: clang-tidy - misc-bool-pointer-implicit-conversion
 
 misc-bool-pointer-implicit-conversion
 =====================================
 
-
-Checks for conditions based on implicit conversion from a bool pointer to
-bool.
+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/trunk/docs/clang-tidy/checks/misc-new-delete-overloads.rst

 .. title:: clang-tidy - misc-new-delete-overloads
 
 misc-new-delete-overloads
 =========================
 
-"cert-dcl54-cpp" redirects here as an alias for this check.
+`cert-dcl54-cpp` redirects here as an alias for this check.
 
-The check flags overloaded operator new() and operator delete() functions that
-do not have a corresponding free store function defined within the same scope.
+The check flags overloaded operator ``new()`` and operator ``delete()``
+functions that do not have a corresponding free store function defined within
+the same scope.
 For instance, the check will flag a class implementation of a non-placement
-operator new() when the class does not also define a non-placement operator
-delete() function as well.
+operator ``new()`` when the class does not also define a non-placement operator
+``delete()`` function as well.
 
 The check does not flag implicitly-defined operators, deleted or private
 operators, or placement operators.
 
 This check corresponds to CERT C++ Coding Standard rule `DCL54-CPP. Overload allocation and deallocation functions as a pair in the same scope
 <https://www.securecoding.cert.org/confluence/display/cplusplus/DCL54-CPP.+Overload+allocation+and+deallocation+functions+as+a+pair+in+the+same+scope>`_.

clang-tools-extra/trunk/docs/clang-tidy/checks/misc-non-copyable-objects.rst

 .. title:: clang-tidy - misc-non-copyable-objects
 
 misc-non-copyable-objects
 =========================
 
-"cert-fio38-c" redirects here as an alias for this check.
+`cert-fio38-c` redirects here as an alias for this check.
 
 The check flags dereferences and non-pointer declarations of objects that are
 not meant to be passed by value, such as C FILE objects or POSIX
-pthread_mutex_t objects.
+``pthread_mutex_t`` objects.
 
 This check corresponds to CERT C++ Coding Standard rule `FIO38-C. Do not copy a FILE object
 <https://www.securecoding.cert.org/confluence/display/c/FIO38-C.+Do+not+copy+a+FILE+object>`_.

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

 .. title:: clang-tidy - misc-static-assert
 
 misc-static-assert
 ==================
 
-"cert-dcl03-c" redirects here as an alias for this check.
+`cert-dcl03-c` redirects here as an alias for this check.
 
 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/trunk/docs/clang-tidy/checks/misc-suspicious-semicolon.rst

 .. title:: clang-tidy - misc-suspicious-semicolon
 
 misc-suspicious-semicolon
 =========================
 
 Finds most instances of stray semicolons that unexpectedly alter the meaning of
-the code. More specifically, it looks for `if`, `while`, `for` and `for-range`
-statements whose body is a single semicolon, and then analyzes the context of
-the code (e.g. indentation) in an attempt to determine whether that is
-intentional.
+the code. More specifically, it looks for ``if``, ``while``, ``for`` and
+``for-range`` statements whose body is a single semicolon, and then analyzes the
+context of the code (e.g. indentation) in an attempt to determine whether that
+is intentional.
 
   .. code-block:: c++
 
     if (x < y);
     {
       x++;
     }
 
-Here the body of the `if` statement consists of only the semicolon at the end of
-the first line, and `x` will be incremented regardless of the condition.
+Here the body of the ``if`` statement consists of only the semicolon at the end
+of the first line, and `x` will be incremented regardless of the condition.
 
 
   .. code-block:: c++
 
     while ((line = readLine(file)) != NULL);
       processLine(line);
 
 As a result of this code, `processLine()` will only be called once, when the
-`while` loop with the empty body exits with `line == NULL`. The indentation of
+``while`` loop with the empty body exits with `line == NULL`. The indentation of
 the code indicates the intention of the programmer.
 
 
   .. code-block:: c++
 
     if (x >= y);
     x -= y;
 

clang-tools-extra/trunk/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst

 .. title:: clang-tidy - misc-throw-by-value-catch-by-reference
 
 misc-throw-by-value-catch-by-reference
 ======================================
 
 "cert-err61-cpp" redirects here as an alias for this check.
 
-Finds violations of the rule "Throw by value, catch by reference" presented for example in "C++ Coding Standards" by H. Sutter and A. Alexandrescu. This check also has the option to find violations of the rule "Throw anonymous temporaries" (https://www.securecoding.cert.org/confluence/display/cplusplus/ERR09-CPP.+Throw+anonymous+temporaries). The option is named ``CheckThrowTemporaries`` and it's on by default.
+Finds violations of the rule "Throw by value, catch by reference" presented for example in "C++ Coding Standards" by H. Sutter and A. Alexandrescu. This check also has the option to find violations of the rule "Throw anonymous temporaries" (https://www.securecoding.cert.org/confluence/display/cplusplus/ERR09-CPP.+Throw+anonymous+temporaries). The option is named :option:`CheckThrowTemporaries` and it's on by default.
 
 Exceptions:
   * Throwing string literals will not be flagged despite being a pointer. They are not susceptible to slicing and the usage of string literals is idomatic.
   * Catching character pointers (``char``, ``wchar_t``, unicode character types) will not be flagged to allow catching sting literals.
   * Moved named values will not be flagged as not throwing an anonymous temporary. In this case we can be sure that the user knows that the object can't be accessed outside catch blocks handling the error.
   * Throwing function parameters will not be flagged as not throwing an anonymous temporary. This allows helper functions for throwing.
   * Re-throwing caught exception variables will not be flragged as not throwing an anonymous temporary. Although this can usually be done by just writing ``throw;`` it happens often enough in real code.

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

 .. title:: clang-tidy - misc-unused-parameters
 
 misc-unused-parameters
 ======================
 
-
-Finds unused parameters and fixes them, so that ``-Wunused-parameter`` can be
+Finds unused parameters and fixes them, so that `-Wunused-parameter` can be
 turned on.

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

 risky
 ^^^^^
 
 In loops where the container expression is more complex than just a
 reference to a declared expression (a variable, function, enum, etc.),
 and some part of it appears elsewhere in the loop, we lower our confidence
 in the transformation due to the increased risk of changing semantics.
 Transformations for these loops are marked as `risky`, and thus will only
-be converted if the minimum required confidence level is set to ``risky``.
+be converted if the minimum required confidence level is set to `risky`.
 
 .. code-block:: c++
 
   int arr[10][20];
   int l = 5;
 
   for (int j = 0; j < 20; ++j)
     int k = arr[l][j] + l; // using l outside arr[l] is considered risky
 
   for (int i = 0; i < obj.getVector().size(); ++i)
     obj.foo(10); // using 'obj' is considered risky
 
 See
 :ref:`Range-based loops evaluate end() only once<IncorrectRiskyTransformation>`
 for an example of an incorrect transformation when the minimum required confidence
 level is set to `risky`.
 
 reasonable (Default)
 ^^^^^^^^^^^^^^^^^^^^
 
 If a loop calls ``.end()`` or ``.size()`` after each iteration, the
 transformation for that loop is marked as `reasonable`, and thus will
-be converted if the required confidence level is set to ``reasonable``
+be converted if the required confidence level is set to `reasonable`
 (default) or lower.
 
 .. code-block:: c++
 
   // using size() is considered reasonable
   for (int i = 0; i < container.size(); ++i)
     cout << container[i];
 
 safe
 ^^^^
 
 Any other loops that do not match the above criteria to be marked as
 `risky` or `reasonable` are marked `safe`, and thus will be converted
-if the required confidence level is set to ``safe`` or lower.
+if the required confidence level is set to `safe` or lower.
 
 .. code-block:: c++
 
   int arr[] = {1,2,3};
 
   for (int i = 0; i < 3; ++i)
     cout << arr[i];
 
.. code-block:: c++
   // reasonable conversion
   for (vector<int>::iterator it = v.begin(); it != v.end(); ++it)
     cout << *it;
 
   // reasonable conversion
   for (int i = 0; i < v.size(); ++i)
     cout << v[i];
 
-After applying the check with minimum confidence level set to ``reasonable`` (default):
+After applying the check with minimum confidence level set to `reasonable` (default):
 
 .. code-block:: c++
 
   const int N = 5;
   int arr[] = {1,2,3,4,5};
   vector<int> v;
   v.push_back(1);
   v.push_back(2);

 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 While most of the check's risk analysis is dedicated to determining whether
 the iterator or container was modified within the loop, it is possible to
 circumvent the analysis by accessing and modifying the container through a
 pointer or reference.
 
 If the container were directly used instead of using the pointer or reference
-the following transformation would have only been applied at the ``risky``
+the following transformation would have only been applied at the `risky`
 level since calling a member function of the container is considered `risky`.
 The check cannot identify expressions associated with the container that are
 different than the one used in the loop header, therefore the transformation
-below ends up being performed at the ``safe`` level.
+below ends up being performed at the `safe` level.
 
 .. code-block:: c++
 
   vector<int> vec;
 
   vector<int> *ptr = &vec;
   vector<int> &ref = vec;
 

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

 
 
 Pass-by-value in constructors
 -----------------------------
 
 Replaces the uses of const-references constructor parameters that are copied
 into class fields. The parameter is then moved with `std::move()`.
 
-Since `std::move()` is a library function declared in `<utility>` it may be
+Since ``std::move()`` is a library function declared in `<utility>` it may be
 necessary to add this include. The check will add the include directive when
 necessary.
 
   .. code-block:: c++
 
      #include <string>
 
      class Foo {

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

.. code-block:: c++
   map_iterator J = MyMap.begin();
 
   // The following implementation-specific iterator type for which
   // std::vector<int>::iterator could be a typedef would not be transformed.
   __gnu_cxx::__normal_iterator<int*, std::vector> K = MyVec.begin();
 
 * The initializer for the variable being declared is not a braced initializer
   list. Otherwise, use of ``auto`` would cause the type of the variable to be
-  deduced as``std::initializer_list``.
+  deduced as ``std::initializer_list``.
 
 New expressions
 ---------------
 
 Frequently, when a pointer is declared and initialized with ``new``, the
 pointee type has to be written twice: in the declaration type and in the
 ``new`` expression. In this cases, the declaration type can be replaced with
 ``auto`` improving readability and maintainability.

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

.. code-block:: c++
   }
 
 
 User defined macros
 -------------------
 
 By default this check will only replace the ``NULL`` macro and will skip any
 user-defined macros that behaves like ``NULL``. The user can use the
-:option:``UserNullMacros`` option to specify a comma-separated list of macro
+:option:`UserNullMacros` option to specify a comma-separated list of macro
 names that will be transformed along with ``NULL``.
 
 Example
 ^^^^^^^
 
 .. code-block:: c++
 
   #define MY_NULL (void*)0
   void assignment() {
     void *p = MY_NULL;
   }
 
 transforms to:
 
 .. code-block:: c++
 
   #define MY_NULL NULL
   void assignment() {
     int *p = nullptr;
   }
 
-if the ``UserNullMacros`` option is set to ``MY_NULL``.
+if the :option:`UserNullMacros` option is set to ``MY_NULL``.

clang-tools-extra/trunk/docs/clang-tidy/checks/performance-implicit-cast-in-loop.rst

 
 .. code:: c++
 
    map<int, vector<string>> my_map;
    for (const pair<int, vector<string>>& p : my_map) {}
    // The iterator type is in fact pair<const int, vector<string>>, which means
    // that the compiler added a cast, resulting in a copy of the vectors.
 
-The easiest solution is usually to use "const auto&" instead of writing the type
+The easiest solution is usually to use ``const auto&`` instead of writing the type
 manually.

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

 .. title:: clang-tidy - readability-braces-around-statements
 
 readability-braces-around-statements
 ====================================
 
+`google-readability-braces-around-statements` redirects here as an alias for
+this check.
 
 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
+Additionally, one can define an option :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/trunk/docs/clang-tidy/checks/readability-function-size.rst

 .. title:: clang-tidy - readability-function-size
 
 readability-function-size
 =========================
 
+`google-readability-function-size` redirects here as an alias for this check.
 
 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
+  * :option:`LineThreshold` - flag functions exceeding this number of lines. The
+    default is `-1` (ignore the number of lines).
+  * :option:`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).
+    macro-heavy code. The default is `800`.
+  * :option:`BranchThreshold` - flag functions exceeding this number of control
+    statements. The default is `-1` (ignore the number of branches).

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

 .. title:: clang-tidy - readability-identifier-naming
 
 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 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/trunk/docs/clang-tidy/checks/readability-named-parameter.rst

 .. title:: clang-tidy - readability-named-parameter
 
 readability-named-parameter
 ===========================
 
-
 Find functions with unnamed arguments.
 
 The check implements the following rule originating in the Google C++ Style
 Guide:
 
 https://google.github.io/styleguide/cppguide.html#Function_Declarations_and_Definitions
 
 All parameters should be named, with identical names in the declaration and
 implementation.
 
-Corresponding cpplint.py check name: 'readability/function'.
+Corresponding cpplint.py check name: `readability/function`.