From 76eae751b599704a9abe267046af018e876e290a Mon Sep 17 00:00:00 2001 From: Alexander Kornienko Date: Thu, 18 Aug 2016 11:06:09 +0000 Subject: [PATCH] [clang-tidy docs] Fix build errors on Sphinx 1.4.5 llvm-svn: 279049 --- ...eguidelines-pro-bounds-constant-array-index.rst | 2 +- .../clang-tidy/checks/misc-assert-side-effect.rst | 14 ++++++---- .../misc-throw-by-value-catch-by-reference.rst | 30 +++++++++++++++++----- .../clang-tidy/checks/modernize-use-nullptr.rst | 13 +++++----- .../docs/clang-tidy/checks/mpi-buffer-deref.rst | 21 +++++++-------- .../readability-braces-around-statements.rst | 21 +++++++++------ .../checks/readability-function-size.rst | 27 ++++++++++++------- clang-tools-extra/docs/clang-tidy/index.rst | 6 ++--- 8 files changed, 86 insertions(+), 48 deletions(-) diff --git a/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines-pro-bounds-constant-array-index.rst b/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines-pro-bounds-constant-array-index.rst index 6e2f55d..39bbf28 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines-pro-bounds-constant-array-index.rst +++ b/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines-pro-bounds-constant-array-index.rst @@ -8,7 +8,7 @@ This check flags all array subscript expressions on static arrays and 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 :option:`GslHeader` has been set +The check can generate fixes after the 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 diff --git a/clang-tools-extra/docs/clang-tidy/checks/misc-assert-side-effect.rst b/clang-tools-extra/docs/clang-tidy/checks/misc-assert-side-effect.rst index a4d84bb..3270d20 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/misc-assert-side-effect.rst +++ b/clang-tools-extra/docs/clang-tidy/checks/misc-assert-side-effect.rst @@ -11,8 +11,12 @@ builds. There are two options: - - :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. +.. 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. diff --git a/clang-tools-extra/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst b/clang-tools-extra/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst index b0fe40d..604be24 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst +++ b/clang-tools-extra/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst @@ -5,11 +5,29 @@ 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 :option:`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. 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. + * 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. + +Options +------- + +.. option:: CheckThrowTemporaries + + Triggers detection of violations of the rule `Throw anonymous temporaries + `_. + Default is `1`. + diff --git a/clang-tools-extra/docs/clang-tidy/checks/modernize-use-nullptr.rst b/clang-tools-extra/docs/clang-tidy/checks/modernize-use-nullptr.rst index 3449eb4..68c19c7 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/modernize-use-nullptr.rst +++ b/clang-tools-extra/docs/clang-tidy/checks/modernize-use-nullptr.rst @@ -36,14 +36,15 @@ transforms to: return nullptr; } +Options +------- -User defined macros -------------------- +.. option:: UserNullMacros -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 -names that will be transformed along with ``NULL``. + 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 + names that will be transformed along with ``NULL``. Example ^^^^^^^ diff --git a/clang-tools-extra/docs/clang-tidy/checks/mpi-buffer-deref.rst b/clang-tools-extra/docs/clang-tidy/checks/mpi-buffer-deref.rst index 6a3f426..ef9f391 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/mpi-buffer-deref.rst +++ b/clang-tools-extra/docs/clang-tidy/checks/mpi-buffer-deref.rst @@ -10,16 +10,17 @@ types, insufficiently dereferenced buffers can be passed, like for example as double pointers or multidimensional arrays, without a compiler warning emitted. Examples: -.. code:: c++ - // A double pointer is passed to the MPI function. - char *buf; - MPI_Send(&buf, 1, MPI_CHAR, 0, 0, MPI_COMM_WORLD); +.. code-block:: c++ - // A multidimensional array is passed to the MPI function. - short buf[1][1]; - MPI_Send(buf, 1, MPI_SHORT, 0, 0, MPI_COMM_WORLD); + // A double pointer is passed to the MPI function. + char *buf; + MPI_Send(&buf, 1, MPI_CHAR, 0, 0, MPI_COMM_WORLD); - // A pointer to an array is passed to the MPI function. - short *buf[1]; - MPI_Send(buf, 1, MPI_SHORT, 0, 0, MPI_COMM_WORLD); + // A multidimensional array is passed to the MPI function. + short buf[1][1]; + MPI_Send(buf, 1, MPI_SHORT, 0, 0, MPI_COMM_WORLD); + + // A pointer to an array is passed to the MPI function. + short *buf[1]; + MPI_Send(buf, 1, MPI_SHORT, 0, 0, MPI_COMM_WORLD); diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability-braces-around-statements.rst b/clang-tools-extra/docs/clang-tidy/checks/readability-braces-around-statements.rst index a60a531..8689382 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability-braces-around-statements.rst +++ b/clang-tools-extra/docs/clang-tidy/checks/readability-braces-around-statements.rst @@ -6,8 +6,8 @@ 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 +Checks that bodies of ``if`` statements and loops (``for``, ``do while``, and +``while``) are inside braces. Before: @@ -24,10 +24,15 @@ After: statement; } -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. +Options +------- + +.. option:: ShortStatementLines + + Defines 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 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). diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability-function-size.rst b/clang-tools-extra/docs/clang-tidy/checks/readability-function-size.rst index cab1398..fbefa97 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability-function-size.rst +++ b/clang-tools-extra/docs/clang-tidy/checks/readability-function-size.rst @@ -7,12 +7,21 @@ readability-function-size Checks for large functions based on various metrics. -These options are supported: - - * :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`. - * :option:`BranchThreshold` - flag functions exceeding this number of control - statements. The default is `-1` (ignore the number of branches). +Options +------- + +.. 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`. + +.. option:: BranchThreshold + + Flag functions exceeding this number of control statements. The default is + `-1` (ignore the number of branches). diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst index 6f57bb9..ae399b5 100644 --- a/clang-tools-extra/docs/clang-tidy/index.rst +++ b/clang-tools-extra/docs/clang-tidy/index.rst @@ -48,7 +48,7 @@ The ``-list-checks`` option lists all the enabled checks. When used without available checks or with any other value of ``-checks=`` to see which checks are enabled by this value. -:: _checks-groups-table: +.. _checks-groups-table: There are currently the following groups of checks: @@ -341,8 +341,8 @@ style used in the project. For code reviews we mostly use `LLVM Phabricator`_. .. _LLVM Phabricator: http://llvm.org/docs/Phabricator.html Next, you need to decide which module the check belongs to. Modules -are located in subdirectories of -``clang-tidy/ ``_ +are located in subdirectories of `clang-tidy/ +`_ and contain checks targeting a certain aspect of code quality (performance, readability, etc.), certain coding style or standard (Google, LLVM, CERT, etc.) or a widely used API (e.g. MPI). Their names are same as user-facing check -- 2.7.4