https://github.com/zeyi2 updated https://github.com/llvm/llvm-project/pull/217672
>From f52f995cc582a83ad8a03ea1d80daa573a157a20 Mon Sep 17 00:00:00 2001 From: Zeyi Xu <[email protected]> Date: Thu, 20 Aug 2026 23:54:38 +0800 Subject: [PATCH] [clang-tidy][docs] Rewrite check docs in six modules to Markdown --- .../checks/altera/single-work-item-barrier.md | 74 ++-- .../checks/altera/struct-pack-align.md | 85 ++-- .../clang-tidy/checks/altera/unroll-loops.md | 166 ++++---- .../comparison-in-temp-failure-retry.md | 54 ++- .../clang-tidy/checks/boost/use-ranges.md | 314 +++++++-------- .../docs/clang-tidy/checks/cert/err33-c.md | 375 +++++++++--------- .../checks/concurrency/mt-unsafe.md | 64 ++- .../fuchsia/statically-constructed-objects.md | 56 +-- .../checks/fuchsia/temporary-objects.md | 57 ++- .../checks/fuchsia/trailing-return.md | 47 ++- 10 files changed, 640 insertions(+), 652 deletions(-) diff --git a/clang-tools-extra/docs/clang-tidy/checks/altera/single-work-item-barrier.md b/clang-tools-extra/docs/clang-tidy/checks/altera/single-work-item-barrier.md index 0e059f1af6e81..308d960c1e1a0 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/altera/single-work-item-barrier.md +++ b/clang-tools-extra/docs/clang-tidy/checks/altera/single-work-item-barrier.md @@ -1,11 +1,11 @@ -.. title:: clang-tidy - altera-single-work-item-barrier +```{title} clang-tidy - altera-single-work-item-barrier +``` -altera-single-work-item-barrier -=============================== +# altera-single-work-item-barrier Finds OpenCL kernel functions that call a barrier function but do not call -an ID function (``get_local_id``, ``get_local_id``, ``get_group_id``, or -``get_local_linear_id``). +an ID function (`get_local_id`, `get_local_id`, `get_group_id`, or +`get_local_linear_id`). These kernels may be viable single work-item kernels, but will be forced to execute as NDRange kernels if using a newer version of the Altera Offline @@ -15,44 +15,42 @@ If using an older version of the Altera Offline Compiler, these kernel functions will be treated as single work-item kernels, which could be inefficient or lead to errors if NDRange semantics were intended. -Based on the `Altera SDK for OpenCL: Best Practices Guide -<https://www.altera.com/en_US/pdfs/literature/hb/opencl-sdk/aocl_optimization_guide.pdf>`_. +Based on the [Altera SDK for OpenCL: Best Practices Guide](https://www.altera.com/en_US/pdfs/literature/hb/opencl-sdk/aocl_optimization_guide.pdf). Examples: -.. code-block:: c++ - - // error: function calls barrier but does not call an ID function. - void __kernel barrier_no_id(__global int * foo, int size) { - for (int i = 0; i < 100; i++) { - foo[i] += 5; - } - barrier(CLK_GLOBAL_MEM_FENCE); +```c++ +// error: function calls barrier but does not call an ID function. +void __kernel barrier_no_id(__global int * foo, int size) { + for (int i = 0; i < 100; i++) { + foo[i] += 5; } - - // ok: function calls barrier and an ID function. - void __kernel barrier_with_id(__global int * foo, int size) { - for (int i = 0; i < 100; i++) { - int tid = get_global_id(0); - foo[tid] += 5; - } - barrier(CLK_GLOBAL_MEM_FENCE); + barrier(CLK_GLOBAL_MEM_FENCE); +} + +// ok: function calls barrier and an ID function. +void __kernel barrier_with_id(__global int * foo, int size) { + for (int i = 0; i < 100; i++) { + int tid = get_global_id(0); + foo[tid] += 5; } - - // ok with AOC Version 17.01: the reqd_work_group_size turns this into - // an NDRange. - __attribute__((reqd_work_group_size(2,2,2))) - void __kernel barrier_with_id(__global int * foo, int size) { - for (int i = 0; i < 100; i++) { - foo[tid] += 5; - } - barrier(CLK_GLOBAL_MEM_FENCE); + barrier(CLK_GLOBAL_MEM_FENCE); +} + +// ok with AOC Version 17.01: the reqd_work_group_size turns this into +// an NDRange. +__attribute__((reqd_work_group_size(2,2,2))) +void __kernel barrier_with_id(__global int * foo, int size) { + for (int i = 0; i < 100; i++) { + foo[tid] += 5; } + barrier(CLK_GLOBAL_MEM_FENCE); +} +``` -Options -------- - -.. option:: AOCVersion +## Options - Defines the version of the Altera Offline Compiler. Defaults to ``1600`` - (corresponding to version 16.00). +```{option} AOCVersion +Defines the version of the Altera Offline Compiler. Default is `1600` +(corresponding to version 16.00). +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/altera/struct-pack-align.md b/clang-tools-extra/docs/clang-tidy/checks/altera/struct-pack-align.md index b03a4fcf7fcf3..ab77344a9703e 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/altera/struct-pack-align.md +++ b/clang-tools-extra/docs/clang-tidy/checks/altera/struct-pack-align.md @@ -1,7 +1,7 @@ -.. title:: clang-tidy - altera-struct-pack-align +```{title} clang-tidy - altera-struct-pack-align +``` -altera-struct-pack-align -======================== +# altera-struct-pack-align Finds structs that are inefficiently packed or aligned, and recommends packing and/or aligning of said structs as needed. @@ -12,43 +12,42 @@ structs that are not well aligned is inefficient. Fix-its are provided to fix both of these issues by inserting and/or amending relevant struct attributes. -Based on the `Altera SDK for OpenCL: Best Practices Guide -<https://www.altera.com/en_US/pdfs/literature/hb/opencl-sdk/aocl_optimization_guide.pdf>`_. - -.. code-block:: c++ - - // The following struct is originally aligned to 4 bytes, and thus takes up - // 12 bytes of memory instead of 10. Packing the struct will make it use - // only 10 bytes of memory, and aligning it to 16 bytes will make it - // efficient to access. - struct example { - char a; // 1 byte - double b; // 8 bytes - char c; // 1 byte - }; - - // The following struct is arranged in such a way that packing is not needed. - // However, it is aligned to 4 bytes instead of 8, and thus needs to be - // explicitly aligned. - struct implicitly_packed_example { - char a; // 1 byte - char b; // 1 byte - char c; // 1 byte - char d; // 1 byte - int e; // 4 bytes - }; - - // The following struct is explicitly aligned and packed. - struct good_example { - char a; // 1 byte - double b; // 8 bytes - char c; // 1 byte - } __attribute__((packed)) __attribute__((aligned(16)); - - // Explicitly aligning a struct to the wrong value will result in a warning. - // The following example should be aligned to 16 bytes, not 32. - struct badly_aligned_example { - char a; // 1 byte - double b; // 8 bytes - char c; // 1 byte - } __attribute__((packed)) __attribute__((aligned(32))); +Based on the [Altera SDK for OpenCL: Best Practices Guide](https://www.altera.com/en_US/pdfs/literature/hb/opencl-sdk/aocl_optimization_guide.pdf). + +```c++ +// The following struct is originally aligned to 4 bytes, and thus takes up +// 12 bytes of memory instead of 10. Packing the struct will make it use +// only 10 bytes of memory, and aligning it to 16 bytes will make it +// efficient to access. +struct example { + char a; // 1 byte + double b; // 8 bytes + char c; // 1 byte +}; + +// The following struct is arranged in such a way that packing is not needed. +// However, it is aligned to 4 bytes instead of 8, and thus needs to be +// explicitly aligned. +struct implicitly_packed_example { + char a; // 1 byte + char b; // 1 byte + char c; // 1 byte + char d; // 1 byte + int e; // 4 bytes +}; + +// The following struct is explicitly aligned and packed. +struct good_example { + char a; // 1 byte + double b; // 8 bytes + char c; // 1 byte +} __attribute__((packed)) __attribute__((aligned(16)); + +// Explicitly aligning a struct to the wrong value will result in a warning. +// The following example should be aligned to 16 bytes, not 32. +struct badly_aligned_example { + char a; // 1 byte + double b; // 8 bytes + char c; // 1 byte +} __attribute__((packed)) __attribute__((aligned(32))); +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/altera/unroll-loops.md b/clang-tools-extra/docs/clang-tidy/checks/altera/unroll-loops.md index 419a1edf02112..158566b580d83 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/altera/unroll-loops.md +++ b/clang-tools-extra/docs/clang-tidy/checks/altera/unroll-loops.md @@ -1,7 +1,7 @@ -.. title:: clang-tidy - altera-unroll-loops +```{title} clang-tidy - altera-unroll-loops +``` -altera-unroll-loops -=================== +# altera-unroll-loops Finds inner loops that have not been unrolled, as well as fully unrolled loops with unknown loop bounds or a large number of iterations. @@ -12,94 +12,92 @@ be fully unrolled, and should be partially unrolled. Notes: -- This check is unable to determine the number of iterations in a ``while`` or - ``do..while`` loop; hence if such a loop is fully unrolled, a note is emitted +- This check is unable to determine the number of iterations in a `while` or + `do..while` loop; hence if such a loop is fully unrolled, a note is emitted advising the user to partially unroll instead. - -- In ``for`` loops, our check only works with simple arithmetic increments ( - ``+``, ``-``, ``*``, ``/``). For all other increments, partial unrolling is +- In `for` loops, our check only works with simple arithmetic increments ( + `+`, `-`, `*`, `/`). For all other increments, partial unrolling is advised. - - Depending on the exit condition, the calculations for determining if the number of iterations is large may be off by 1. This should not be an issue since the cut-off is generally arbitrary. -Based on the `Altera SDK for OpenCL: Best Practices Guide -<https://www.altera.com/en_US/pdfs/literature/hb/opencl-sdk/aocl_optimization_guide.pdf>`_. - -.. code-block:: c++ - - for (int i = 0; i < 10; i++) { // ok: outer loops should not be unrolled - int j = 0; - do { // warning: this inner do..while loop should be unrolled - j++; - } while (j < 15); - - int k = 0; - #pragma unroll - while (k < 20) { // ok: this inner loop is already unrolled - k++; - } - } - - int A[1000]; - #pragma unroll - // warning: this loop is large and should be partially unrolled - for (int a : A) { - printf("%d", a); - } +Based on the [Altera SDK for OpenCL: Best Practices Guide](https://www.altera.com/en_US/pdfs/literature/hb/opencl-sdk/aocl_optimization_guide.pdf). - #pragma unroll 5 - // ok: this loop is large, but is partially unrolled - for (int a : A) { - printf("%d", a); - } +```c++ +for (int i = 0; i < 10; i++) { // ok: outer loops should not be unrolled + int j = 0; + do { // warning: this inner do..while loop should be unrolled + j++; + } while (j < 15); + int k = 0; #pragma unroll - // warning: this loop is large and should be partially unrolled - for (int i = 0; i < 1000; ++i) { - printf("%d", i); + while (k < 20) { // ok: this inner loop is already unrolled + k++; } - - #pragma unroll 5 - // ok: this loop is large, but is partially unrolled - for (int i = 0; i < 1000; ++i) { - printf("%d", i); - } - - #pragma unroll - // warning: << operator not supported, recommend partial unrolling - for (int i = 0; i < 1000; i<<1) { - printf("%d", i); - } - - std::vector<int> someVector (100, 0); - int i = 0; - #pragma unroll - // note: loop may be large, recommend partial unrolling - while (i < someVector.size()) { - someVector[i]++; - } - - #pragma unroll - // note: loop may be large, recommend partial unrolling - while (true) { - printf("In loop"); - } - - #pragma unroll 5 - // ok: loop may be large, but is partially unrolled - while (i < someVector.size()) { - someVector[i]++; - } - -Options -------- - -.. option:: MaxLoopIterations - - Defines the maximum number of loop iterations that a fully unrolled loop - can have. By default, it is set to `100`. - - In practice, this refers to the integer value of the upper bound - within the loop statement's condition expression. +} + +int A[1000]; +#pragma unroll +// warning: this loop is large and should be partially unrolled +for (int a : A) { + printf("%d", a); +} + +#pragma unroll 5 +// ok: this loop is large, but is partially unrolled +for (int a : A) { + printf("%d", a); +} + +#pragma unroll +// warning: this loop is large and should be partially unrolled +for (int i = 0; i < 1000; ++i) { + printf("%d", i); +} + +#pragma unroll 5 +// ok: this loop is large, but is partially unrolled +for (int i = 0; i < 1000; ++i) { + printf("%d", i); +} + +#pragma unroll +// warning: << operator not supported, recommend partial unrolling +for (int i = 0; i < 1000; i<<1) { + printf("%d", i); +} + +std::vector<int> someVector (100, 0); +int i = 0; +#pragma unroll +// note: loop may be large, recommend partial unrolling +while (i < someVector.size()) { + someVector[i]++; +} + +#pragma unroll +// note: loop may be large, recommend partial unrolling +while (true) { + printf("In loop"); +} + +#pragma unroll 5 +// ok: loop may be large, but is partially unrolled +while (i < someVector.size()) { + someVector[i]++; +} +``` + +## Options + +```{option} MaxLoopIterations +Defines the maximum number of loop iterations that a fully unrolled loop +can have. + +In practice, this refers to the integer value of the upper bound +within the loop statement's condition expression. + +Default is `100`. +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/android/comparison-in-temp-failure-retry.md b/clang-tools-extra/docs/clang-tidy/checks/android/comparison-in-temp-failure-retry.md index 42e8dd97452ef..2f7c5cad3c041 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/android/comparison-in-temp-failure-retry.md +++ b/clang-tools-extra/docs/clang-tidy/checks/android/comparison-in-temp-failure-retry.md @@ -1,44 +1,42 @@ -.. title:: clang-tidy - android-comparison-in-temp-failure-retry +```{title} clang-tidy - android-comparison-in-temp-failure-retry +``` -android-comparison-in-temp-failure-retry -======================================== +# android-comparison-in-temp-failure-retry Diagnoses comparisons that appear to be incorrectly placed in the argument to -the ``TEMP_FAILURE_RETRY`` macro. Having such a use is incorrect in the vast +the `TEMP_FAILURE_RETRY` macro. Having such a use is incorrect in the vast majority of cases, and will often silently defeat the purpose of the -``TEMP_FAILURE_RETRY`` macro. +`TEMP_FAILURE_RETRY` macro. -For context, ``TEMP_FAILURE_RETRY`` is `a convenience macro -<https://www.gnu.org/software/libc/manual/html_node/Interrupted-Primitives.html>`_ +For context, `TEMP_FAILURE_RETRY` is [a convenience macro](https://www.gnu.org/software/libc/manual/html_node/Interrupted-Primitives.html) provided by both glibc and Bionic. Its purpose is to repeatedly run a syscall until it either succeeds, or fails for reasons other than being interrupted. Example buggy usage looks like: -.. code-block:: c +```c +char cs[1]; +while (TEMP_FAILURE_RETRY(read(STDIN_FILENO, cs, sizeof(cs)) != 0)) { + // Do something with cs. +} +``` - char cs[1]; - while (TEMP_FAILURE_RETRY(read(STDIN_FILENO, cs, sizeof(cs)) != 0)) { - // Do something with cs. - } - -Because ``TEMP_FAILURE_RETRY`` will check for whether the result -*of the comparison* is ``-1``, and retry if so. +Because `TEMP_FAILURE_RETRY` will check for whether the result +*of the comparison* is `-1`, and retry if so. If you encounter this, the fix is simple: lift the comparison out of the -``TEMP_FAILURE_RETRY`` argument, like so: - -.. code-block:: c - - char cs[1]; - while (TEMP_FAILURE_RETRY(read(STDIN_FILENO, cs, sizeof(cs))) != 0) { - // Do something with cs. - } +`TEMP_FAILURE_RETRY` argument, like so: -Options -------- +```c +char cs[1]; +while (TEMP_FAILURE_RETRY(read(STDIN_FILENO, cs, sizeof(cs))) != 0) { + // Do something with cs. +} +``` -.. option:: RetryMacros +## Options - A comma-separated list of the names of retry macros to be checked. - Default is `TEMP_FAILURE_RETRY`. +```{option} RetryMacros +A comma-separated list of the names of retry macros to be checked. +Default is `TEMP_FAILURE_RETRY`. +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/boost/use-ranges.md b/clang-tools-extra/docs/clang-tidy/checks/boost/use-ranges.md index 6cf54347ad613..10f6c8db23045 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/boost/use-ranges.md +++ b/clang-tools-extra/docs/clang-tidy/checks/boost/use-ranges.md @@ -1,187 +1,187 @@ -.. title:: clang-tidy - boost-use-ranges +```{title} clang-tidy - boost-use-ranges +``` -boost-use-ranges -================ +# boost-use-ranges Detects calls to standard library iterator algorithms that could be replaced with a Boost ranges version instead. -Example -------- - -.. code-block:: c++ - - auto Iter1 = std::find(Items.begin(), Items.end(), 0); - auto AreSame = std::equal(Items1.cbegin(), Items1.cend(), std::begin(Items2), - std::end(Items2)); +## Example +```c++ +auto Iter1 = std::find(Items.begin(), Items.end(), 0); +auto AreSame = std::equal(Items1.cbegin(), Items1.cend(), std::begin(Items2), + std::end(Items2)); +``` Transforms to: -.. code-block:: c++ - - auto Iter1 = boost::range::find(Items, 0); - auto AreSame = boost::range::equal(Items1, Items2); +```c++ +auto Iter1 = boost::range::find(Items, 0); +auto AreSame = boost::range::equal(Items1, Items2); +``` -Supported algorithms --------------------- +## Supported algorithms Calls to the following std library algorithms are checked: -``std::accumulate``, -``std::adjacent_difference``, -``std::adjacent_find``, -``std::all_of``, -``std::any_of``, -``std::binary_search``, -``std::copy_backward``, -``std::copy_if``, -``std::copy``, -``std::count_if``, -``std::count``, -``std::equal_range``, -``std::equal``, -``std::fill``, -``std::find_end``, -``std::find_first_of``, -``std::find_if_not``, -``std::find_if``, -``std::find``, -``std::for_each``, -``std::generate``, -``std::includes``, -``std::iota``, -``std::is_partitioned``, -``std::is_permutation``, -``std::is_sorted_until``, -``std::is_sorted``, -``std::lexicographical_compare``, -``std::lower_bound``, -``std::make_heap``, -``std::max_element``, -``std::merge``, -``std::min_element``, -``std::mismatch``, -``std::next_permutation``, -``std::none_of``, -``std::partial_sum``, -``std::partial_sort_copy``, -``std::partition_copy``, -``std::partition_point``, -``std::partition``, -``std::pop_heap``, -``std::prev_permutation``, -``std::push_heap``, -``std::random_shuffle``, -``std::reduce``, -``std::remove_copy_if``, -``std::remove_copy``, -``std::remove_if``, -``std::remove``, -``std::replace_copy_if``, -``std::replace_copy``, -``std::replace_if``, -``std::replace``, -``std::reverse_copy``, -``std::reverse``, -``std::search``, -``std::set_difference``, -``std::set_intersection``, -``std::set_symmetric_difference``, -``std::set_union``, -``std::sort_heap``, -``std::sort``, -``std::stable_partition``, -``std::stable_sort``, -``std::transform``, -``std::unique_copy``, -``std::unique``, -``std::upper_bound``. +- `std::accumulate` +- `std::adjacent_difference` +- `std::adjacent_find` +- `std::all_of` +- `std::any_of` +- `std::binary_search` +- `std::copy_backward` +- `std::copy_if` +- `std::copy` +- `std::count_if` +- `std::count` +- `std::equal_range` +- `std::equal` +- `std::fill` +- `std::find_end` +- `std::find_first_of` +- `std::find_if_not` +- `std::find_if` +- `std::find` +- `std::for_each` +- `std::generate` +- `std::includes` +- `std::iota` +- `std::is_partitioned` +- `std::is_permutation` +- `std::is_sorted_until` +- `std::is_sorted` +- `std::lexicographical_compare` +- `std::lower_bound` +- `std::make_heap` +- `std::max_element` +- `std::merge` +- `std::min_element` +- `std::mismatch` +- `std::next_permutation` +- `std::none_of` +- `std::partial_sum` +- `std::partial_sort_copy` +- `std::partition_copy` +- `std::partition_point` +- `std::partition` +- `std::pop_heap` +- `std::prev_permutation` +- `std::push_heap` +- `std::random_shuffle` +- `std::reduce` +- `std::remove_copy_if` +- `std::remove_copy` +- `std::remove_if` +- `std::remove` +- `std::replace_copy_if` +- `std::replace_copy` +- `std::replace_if` +- `std::replace` +- `std::reverse_copy` +- `std::reverse` +- `std::search` +- `std::set_difference` +- `std::set_intersection` +- `std::set_symmetric_difference` +- `std::set_union` +- `std::sort_heap` +- `std::sort` +- `std::stable_partition` +- `std::stable_sort` +- `std::transform` +- `std::unique_copy` +- `std::unique` +- `std::upper_bound` The check will also look for the following functions from the -``boost::algorithm`` namespace: - -``all_of_equal``, -``any_of_equal``, -``any_of``, -``apply_permutation``, -``apply_reverse_permutation``, -``clamp_range``, -``copy_if_until``, -``copy_if_while``, -``copy_if``, -``copy_until``, -``copy_while``, -``find_backward``, -``find_if_backward``, -``find_if_not_backward``, -``find_if_not``, -``find_not_backward``, -``hex_lower``, -``hex``, -``iota``, ``all_of``, -``is_decreasing``, -``is_increasing``, -``is_palindrome``, -``is_partitioned_until``, -``is_partitioned``, -``is_permutation``, -``is_sorted_until``, -``is_sorted``, -``is_strictly_decreasing``, -``is_strictly_increasing``, -``none_of_equal``, -``none_of``, -``one_of_equal``, -``one_of``, -``partition_copy``, -``partition_point``, -``reduce``, -``unhex``. - -Reverse Iteration ------------------ +`boost::algorithm` namespace: + +- `all_of_equal` +- `any_of_equal` +- `any_of` +- `apply_permutation` +- `apply_reverse_permutation` +- `clamp_range` +- `copy_if_until` +- `copy_if_while` +- `copy_if` +- `copy_until` +- `copy_while` +- `find_backward` +- `find_if_backward` +- `find_if_not_backward` +- `find_if_not` +- `find_not_backward` +- `hex_lower` +- `hex` +- `iota` +- `all_of` +- `is_decreasing` +- `is_increasing` +- `is_palindrome` +- `is_partitioned_until` +- `is_partitioned` +- `is_permutation` +- `is_sorted_until` +- `is_sorted` +- `is_strictly_decreasing` +- `is_strictly_increasing` +- `none_of_equal` +- `none_of` +- `one_of_equal` +- `one_of` +- `partition_copy` +- `partition_point` +- `reduce` +- `unhex` + +## Reverse Iteration If calls are made using reverse iterators on containers, The code will be -fixed using the ``boost::adaptors::reverse`` adaptor. +fixed using the `boost::adaptors::reverse` adaptor. -.. code-block:: c++ - - auto AreSame = std::equal(Items1.rbegin(), Items1.rend(), - std::crbegin(Items2), std::crend(Items2)); +```c++ +auto AreSame = std::equal(Items1.rbegin(), Items1.rend(), + std::crbegin(Items2), std::crend(Items2)); +``` Transforms to: -.. code-block:: c++ - - auto AreSame = boost::range::equal(boost::adaptors::reverse(Items1), - boost::adaptors::reverse(Items2)); +```c++ +auto AreSame = boost::range::equal(boost::adaptors::reverse(Items1), + boost::adaptors::reverse(Items2)); +``` -Options -------- +## Options -.. option:: IncludeStyle +```{option} IncludeStyle +A string specifying which include-style is used, `llvm` or `google`. +Default is `llvm`. +``` - A string specifying which include-style is used, `llvm` or `google`. Default - is `llvm`. +```{option} IncludeBoostSystem +When `true`, the Boost headers are included as system headers +with angle brackets (`#include <boost.hpp>`), otherwise quotes are used +(`#include "boost.hpp"`). -.. option:: IncludeBoostSystem +Default is `true`. +``` - If `true` (default value) the boost headers are included as system headers - with angle brackets (`#include <boost.hpp>`), otherwise quotes are used - (`#include "boost.hpp"`). +````{option} UseReversePipe +When `true`, fixes which involve reverse ranges will use the +pipe adaptor syntax instead of the function syntax. -.. option:: UseReversePipe +```c++ +std::find(Items.rbegin(), Items.rend(), 0); +``` - When `true` (default `false`), fixes which involve reverse ranges will use the - pipe adaptor syntax instead of the function syntax. - - .. code-block:: c++ - - std::find(Items.rbegin(), Items.rend(), 0); - - Transforms to: +Transforms to: - .. code-block:: c++ +```c++ +boost::range::find(Items | boost::adaptors::reversed, 0); +``` - boost::range::find(Items | boost::adaptors::reversed, 0); +Default is `false`. +```` diff --git a/clang-tools-extra/docs/clang-tidy/checks/cert/err33-c.md b/clang-tools-extra/docs/clang-tidy/checks/cert/err33-c.md index ac974c5e93de6..7af9020bbcc2f 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/cert/err33-c.md +++ b/clang-tools-extra/docs/clang-tidy/checks/cert/err33-c.md @@ -1,202 +1,201 @@ -.. title:: clang-tidy - cert-err33-c +```{title} clang-tidy - cert-err33-c +``` -cert-err33-c -============ +# cert-err33-c Warns on unused function return values. Many of the standard library functions return a value that indicates if the call was successful. Ignoring the returned value can cause unexpected behavior if an error has occurred. The following functions are checked: -* aligned_alloc() -* asctime_s() -* at_quick_exit() -* atexit() -* bsearch() -* bsearch_s() -* btowc() -* c16rtomb() -* c32rtomb() -* calloc() -* clock() -* cnd_broadcast() -* cnd_init() -* cnd_signal() -* cnd_timedwait() -* cnd_wait() -* ctime_s() -* fclose() -* fflush() -* fgetc() -* fgetpos() -* fgets() -* fgetwc() -* fopen() -* fopen_s() -* fprintf() -* fprintf_s() -* fputc() -* fputs() -* fputwc() -* fputws() -* fread() -* freopen() -* freopen_s() -* fscanf() -* fscanf_s() -* fseek() -* fsetpos() -* ftell() -* fwprintf() -* fwprintf_s() -* fwrite() -* fwscanf() -* fwscanf_s() -* getc() -* getchar() -* getenv() -* getenv_s() -* gets_s() -* getwc() -* getwchar() -* gmtime() -* gmtime_s() -* localtime() -* localtime_s() -* malloc() -* mbrtoc16() -* mbrtoc32() -* mbsrtowcs() -* mbsrtowcs_s() -* mbstowcs() -* mbstowcs_s() -* memchr() -* mktime() -* mtx_init() -* mtx_lock() -* mtx_timedlock() -* mtx_trylock() -* mtx_unlock() -* printf_s() -* putc() -* putwc() -* raise() -* realloc() -* remove() -* rename() -* setlocale() -* setvbuf() -* scanf() -* scanf_s() -* signal() -* snprintf() -* snprintf_s() -* sprintf() -* sprintf_s() -* sscanf() -* sscanf_s() -* strchr() -* strerror_s() -* strftime() -* strpbrk() -* strrchr() -* strstr() -* strtod() -* strtof() -* strtoimax() -* strtok() -* strtok_s() -* strtol() -* strtold() -* strtoll() -* strtoumax() -* strtoul() -* strtoull() -* strxfrm() -* swprintf() -* swprintf_s() -* swscanf() -* swscanf_s() -* thrd_create() -* thrd_detach() -* thrd_join() -* thrd_sleep() -* time() -* timespec_get() -* tmpfile() -* tmpfile_s() -* tmpnam() -* tmpnam_s() -* tss_create() -* tss_get() -* tss_set() -* ungetc() -* ungetwc() -* vfprintf() -* vfprintf_s() -* vfscanf() -* vfscanf_s() -* vfwprintf() -* vfwprintf_s() -* vfwscanf() -* vfwscanf_s() -* vprintf_s() -* vscanf() -* vscanf_s() -* vsnprintf() -* vsnprintf_s() -* vsprintf() -* vsprintf_s() -* vsscanf() -* vsscanf_s() -* vswprintf() -* vswprintf_s() -* vswscanf() -* vswscanf_s() -* vwprintf_s() -* vwscanf() -* vwscanf_s() -* wcrtomb() -* wcschr() -* wcsftime() -* wcspbrk() -* wcsrchr() -* wcsrtombs() -* wcsrtombs_s() -* wcsstr() -* wcstod() -* wcstof() -* wcstoimax() -* wcstok() -* wcstok_s() -* wcstol() -* wcstold() -* wcstoll() -* wcstombs() -* wcstombs_s() -* wcstoumax() -* wcstoul() -* wcstoull() -* wcsxfrm() -* wctob() -* wctrans() -* wctype() -* wmemchr() -* wprintf_s() -* wscanf() -* wscanf_s() +- `aligned_alloc()` +- `asctime_s()` +- `at_quick_exit()` +- `atexit()` +- `bsearch()` +- `bsearch_s()` +- `btowc()` +- `c16rtomb()` +- `c32rtomb()` +- `calloc()` +- `clock()` +- `cnd_broadcast()` +- `cnd_init()` +- `cnd_signal()` +- `cnd_timedwait()` +- `cnd_wait()` +- `ctime_s()` +- `fclose()` +- `fflush()` +- `fgetc()` +- `fgetpos()` +- `fgets()` +- `fgetwc()` +- `fopen()` +- `fopen_s()` +- `fprintf()` +- `fprintf_s()` +- `fputc()` +- `fputs()` +- `fputwc()` +- `fputws()` +- `fread()` +- `freopen()` +- `freopen_s()` +- `fscanf()` +- `fscanf_s()` +- `fseek()` +- `fsetpos()` +- `ftell()` +- `fwprintf()` +- `fwprintf_s()` +- `fwrite()` +- `fwscanf()` +- `fwscanf_s()` +- `getc()` +- `getchar()` +- `getenv()` +- `getenv_s()` +- `gets_s()` +- `getwc()` +- `getwchar()` +- `gmtime()` +- `gmtime_s()` +- `localtime()` +- `localtime_s()` +- `malloc()` +- `mbrtoc16()` +- `mbrtoc32()` +- `mbsrtowcs()` +- `mbsrtowcs_s()` +- `mbstowcs()` +- `mbstowcs_s()` +- `memchr()` +- `mktime()` +- `mtx_init()` +- `mtx_lock()` +- `mtx_timedlock()` +- `mtx_trylock()` +- `mtx_unlock()` +- `printf_s()` +- `putc()` +- `putwc()` +- `raise()` +- `realloc()` +- `remove()` +- `rename()` +- `setlocale()` +- `setvbuf()` +- `scanf()` +- `scanf_s()` +- `signal()` +- `snprintf()` +- `snprintf_s()` +- `sprintf()` +- `sprintf_s()` +- `sscanf()` +- `sscanf_s()` +- `strchr()` +- `strerror_s()` +- `strftime()` +- `strpbrk()` +- `strrchr()` +- `strstr()` +- `strtod()` +- `strtof()` +- `strtoimax()` +- `strtok()` +- `strtok_s()` +- `strtol()` +- `strtold()` +- `strtoll()` +- `strtoumax()` +- `strtoul()` +- `strtoull()` +- `strxfrm()` +- `swprintf()` +- `swprintf_s()` +- `swscanf()` +- `swscanf_s()` +- `thrd_create()` +- `thrd_detach()` +- `thrd_join()` +- `thrd_sleep()` +- `time()` +- `timespec_get()` +- `tmpfile()` +- `tmpfile_s()` +- `tmpnam()` +- `tmpnam_s()` +- `tss_create()` +- `tss_get()` +- `tss_set()` +- `ungetc()` +- `ungetwc()` +- `vfprintf()` +- `vfprintf_s()` +- `vfscanf()` +- `vfscanf_s()` +- `vfwprintf()` +- `vfwprintf_s()` +- `vfwscanf()` +- `vfwscanf_s()` +- `vprintf_s()` +- `vscanf()` +- `vscanf_s()` +- `vsnprintf()` +- `vsnprintf_s()` +- `vsprintf()` +- `vsprintf_s()` +- `vsscanf()` +- `vsscanf_s()` +- `vswprintf()` +- `vswprintf_s()` +- `vswscanf()` +- `vswscanf_s()` +- `vwprintf_s()` +- `vwscanf()` +- `vwscanf_s()` +- `wcrtomb()` +- `wcschr()` +- `wcsftime()` +- `wcspbrk()` +- `wcsrchr()` +- `wcsrtombs()` +- `wcsrtombs_s()` +- `wcsstr()` +- `wcstod()` +- `wcstof()` +- `wcstoimax()` +- `wcstok()` +- `wcstok_s()` +- `wcstol()` +- `wcstold()` +- `wcstoll()` +- `wcstombs()` +- `wcstombs_s()` +- `wcstoumax()` +- `wcstoul()` +- `wcstoull()` +- `wcsxfrm()` +- `wctob()` +- `wctrans()` +- `wctype()` +- `wmemchr()` +- `wprintf_s()` +- `wscanf()` +- `wscanf_s()` -This check is an alias of check :doc:`bugprone-unused-return-value +This check is an alias of check {doc}`bugprone-unused-return-value <../bugprone/unused-return-value>` with a fixed set of functions. -Suppressing issues by casting to ``void`` is enabled by default and can be -disabled by setting `AllowCastToVoid` option to `false`. +Suppressing issues by casting to `void` is enabled by default and can be +disabled by setting {option}`AllowCastToVoid` to `false`. -The check corresponds to a part of CERT C Coding Standard rule `ERR33-C. -Detect and handle standard library errors -<https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/error-handling-err/err33-c/>`_. +The check corresponds to a part of CERT C Coding Standard rule [ERR33-C. +Detect and handle standard library errors](https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/error-handling-err/err33-c/). The list of checked functions is taken from the rule, with following exception: -* The check can not differentiate if a function is called with ``NULL`` +- The check can not differentiate if a function is called with `NULL` argument. Therefore the following functions are not checked: - ``mblen``, ``mbrlen``, ``mbrtowc``, ``mbtowc``, ``wctomb``, ``wctomb_s`` + `mblen`, `mbrlen`, `mbrtowc`, `mbtowc`, `wctomb`, `wctomb_s` diff --git a/clang-tools-extra/docs/clang-tidy/checks/concurrency/mt-unsafe.md b/clang-tools-extra/docs/clang-tidy/checks/concurrency/mt-unsafe.md index 337be787d962b..0348f2e293cad 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/concurrency/mt-unsafe.md +++ b/clang-tools-extra/docs/clang-tidy/checks/concurrency/mt-unsafe.md @@ -1,12 +1,13 @@ -.. title:: clang-tidy - concurrency-mt-unsafe +```{title} clang-tidy - concurrency-mt-unsafe +``` -concurrency-mt-unsafe -===================== +# concurrency-mt-unsafe Checks for some thread-unsafe functions against a black list of known-to-be-unsafe functions. Usually they access static variables without synchronization (e.g. gmtime(3)) or utilize signals in a racy way. -The set of functions to check is specified with the `FunctionSet` option. +The set of functions to check is specified with the {option}`FunctionSet` +option. Note that using some thread-unsafe functions may be still valid in concurrent programming if only a single thread is used (e.g. setenv(3)), @@ -15,41 +16,38 @@ would be clobbered by subsequent (non-parallel, but concurrent) calls to a related function. E.g. the following code suffers from unprotected accesses to a global state: -.. code-block:: c++ - - // getnetent(3) maintains global state with DB connection, etc. - // If a concurrent green thread calls getnetent(3), the global state is corrupted. - netent = getnetent(); - yield(); - netent = getnetent(); - +```c++ +// getnetent(3) maintains global state with DB connection, etc. +// If a concurrent green thread calls getnetent(3), the global state is corrupted. +netent = getnetent(); +yield(); +netent = getnetent(); +``` Examples: -.. code-block:: c++ - - tm = gmtime(timep); // uses a global buffer - - sleep(1); // implementation may use SIGALRM - -Options -------- +```c++ +tm = gmtime(timep); // uses a global buffer -.. option:: FunctionSet +sleep(1); // implementation may use SIGALRM +``` - Specifies which functions in libc should be considered thread-safe, - possible values are `posix`, `glibc`, or `any`. +## Options - `posix` means POSIX defined thread-unsafe functions. POSIX.1-2001 - in "2.9.1 Thread-Safety" defines that all functions specified in the - standard are thread-safe except a predefined list of thread-unsafe - functions. +```{option} FunctionSet +Specifies which functions in libc should be considered thread-safe, +possible values are `posix`, `glibc`, or `any`. - Glibc defines some of them as thread-safe (e.g. dirname(3)), but adds - non-POSIX thread-unsafe ones (e.g. getopt_long(3)). Glibc's list is - compiled from GNU web documentation with a search for MT-Safe tag: - https://www.gnu.org/software/libc/manual/html_node/POSIX-Safety-Concepts.html +`posix` means POSIX defined thread-unsafe functions. POSIX.1-2001 +in "2.9.1 Thread-Safety" defines that all functions specified in the +standard are thread-safe except a predefined list of thread-unsafe +functions. - If you want to identify thread-unsafe API for at least one libc or - unsure which libc will be used, use `any` (default). +Glibc defines some of them as thread-safe (e.g. dirname(3)), but adds +non-POSIX thread-unsafe ones (e.g. getopt_long(3)). Glibc's list is +compiled from GNU web documentation with a search for MT-Safe tag: +<https://www.gnu.org/software/libc/manual/html_node/POSIX-Safety-Concepts.html> +Use `any` to identify thread-unsafe API for at least one libc or when unsure +which libc will be used. Default is `any`. +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/fuchsia/statically-constructed-objects.md b/clang-tools-extra/docs/clang-tidy/checks/fuchsia/statically-constructed-objects.md index 7153853f05eba..32d32b3ce402a 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/fuchsia/statically-constructed-objects.md +++ b/clang-tools-extra/docs/clang-tidy/checks/fuchsia/statically-constructed-objects.md @@ -1,43 +1,43 @@ -.. title:: clang-tidy - fuchsia-statically-constructed-objects +```{title} clang-tidy - fuchsia-statically-constructed-objects +``` -fuchsia-statically-constructed-objects -====================================== +# fuchsia-statically-constructed-objects Warns if global, non-trivial objects with static storage are constructed, -unless the object is statically initialized with a ``constexpr`` constructor +unless the object is statically initialized with a `constexpr` constructor or has no explicit constructor. For example: -.. code-block:: c++ +```c++ +class A {}; - class A {}; +class B { +public: + B(int Val) : Val(Val) {} +private: + int Val; +}; - class B { - public: - B(int Val) : Val(Val) {} - private: - int Val; - }; +class C { +public: + constexpr C(int Val) : Val(Val) {} + C(int Val1, int Val2) : Val(Val1+Val2) {} - class C { - public: - constexpr C(int Val) : Val(Val) {} - C(int Val1, int Val2) : Val(Val1+Val2) {} +private: + int Val; +}; - private: - int Val; - }; +static A a; // No warning, as there is no explicit constructor +static C c(0); // No warning, as constructor is constexpr - static A a; // No warning, as there is no explicit constructor - static C c(0); // No warning, as constructor is constexpr +static B b(0); // Warning, as constructor is not constexpr +static C c2(0, 1); // Warning, as constructor is not constexpr - static B b(0); // Warning, as constructor is not constexpr - static C c2(0, 1); // Warning, as constructor is not constexpr +static int i; // No warning, as it is trivial - static int i; // No warning, as it is trivial +extern int get_i(); +static C c3(get_i());// Warning, as the constructor is dynamically initialized +``` - extern int get_i(); - static C c3(get_i());// Warning, as the constructor is dynamically initialized - -See the features disallowed in Fuchsia at https://fuchsia.dev/fuchsia-src/development/languages/c-cpp/cxx +See the features disallowed in Fuchsia at <https://fuchsia.dev/fuchsia-src/development/languages/c-cpp/cxx> diff --git a/clang-tools-extra/docs/clang-tidy/checks/fuchsia/temporary-objects.md b/clang-tools-extra/docs/clang-tidy/checks/fuchsia/temporary-objects.md index 5615fe778ad8c..e584273b2909e 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/fuchsia/temporary-objects.md +++ b/clang-tools-extra/docs/clang-tidy/checks/fuchsia/temporary-objects.md @@ -1,7 +1,7 @@ -.. title:: clang-tidy - fuchsia-temporary-objects +```{title} clang-tidy - fuchsia-temporary-objects +``` -fuchsia-temporary-objects -========================= +# fuchsia-temporary-objects Warns on construction of specific temporary objects in the Zircon kernel. If the object should be flagged, the fully qualified type name must be @@ -10,28 +10,28 @@ explicitly passed to the check. For example, given the list of classes "Foo" and "NS::Bar", all of the following will trigger the warning: -.. code-block:: c++ +```c++ +Foo(); +Foo F = Foo(); +func(Foo()); - Foo(); - Foo F = Foo(); - func(Foo()); +namespace NS { - namespace NS { +Bar(); - Bar(); - - } +} +``` With the same list, the following will not trigger the warning: -.. code-block:: c++ - - Foo F; // Non-temporary construction okay - Foo F(param); // Non-temporary construction okay - Foo *F = new Foo(); // New construction okay +```c++ +Foo F; // Non-temporary construction okay +Foo F(param); // Non-temporary construction okay +Foo *F = new Foo(); // New construction okay - Bar(); // Not NS::Bar, so okay - NS::Bar B; // Non-temporary construction okay +Bar(); // Not NS::Bar, so okay +NS::Bar B; // Non-temporary construction okay +``` Note that objects must be explicitly specified in order to be flagged, and so objects that inherit a specified object will not be flagged. @@ -39,17 +39,16 @@ and so objects that inherit a specified object will not be flagged. This check matches temporary objects without regard for inheritance and so a prohibited base class type does not similarly prohibit derived class types. -.. code-block:: c++ - - class Derived : Foo {} // Derived is not explicitly disallowed - Derived(); // and so temporary construction is okay - -Options -------- +```c++ +class Derived : Foo {} // Derived is not explicitly disallowed +Derived(); // and so temporary construction is okay +``` -.. option:: Names +## Options - A semi-colon-separated list of fully-qualified names of C++ classes that - should not be constructed as temporaries. Default is empty string. +```{option} Names +A semi-colon-separated list of fully-qualified names of C++ classes that +should not be constructed as temporaries. Default is empty string. +``` -See the features disallowed in Fuchsia at https://fuchsia.dev/fuchsia-src/development/languages/c-cpp/cxx +See the features disallowed in Fuchsia at <https://fuchsia.dev/fuchsia-src/development/languages/c-cpp/cxx> diff --git a/clang-tools-extra/docs/clang-tidy/checks/fuchsia/trailing-return.md b/clang-tools-extra/docs/clang-tidy/checks/fuchsia/trailing-return.md index a88ec0c7f4ca4..b8f5de18e2a5b 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/fuchsia/trailing-return.md +++ b/clang-tools-extra/docs/clang-tidy/checks/fuchsia/trailing-return.md @@ -1,35 +1,34 @@ -.. title:: clang-tidy - fuchsia-trailing-return +```{title} clang-tidy - fuchsia-trailing-return +``` -fuchsia-trailing-return -======================= +# fuchsia-trailing-return Functions that have trailing returns are disallowed, except for those using -``decltype`` specifiers and lambda with otherwise unutterable return types. +`decltype` specifiers and lambda with otherwise unutterable return types. For example: -.. code-block:: c++ +```c++ +// No warning +int add_one(const int arg) { return arg; } - // No warning - int add_one(const int arg) { return arg; } +// Warning +auto get_add_one() -> int (*)(const int) { + return add_one; +} +``` - // Warning - auto get_add_one() -> int (*)(const int) { - return add_one; - } +Exceptions are made for lambdas and `decltype` specifiers: -Exceptions are made for lambdas and ``decltype`` specifiers: +```c++ +// No warning +auto lambda = [](double x, double y) -> double {return x + y;}; -.. code-block:: c++ +// No warning +template <typename T1, typename T2> +auto fn(const T1 &lhs, const T2 &rhs) -> decltype(lhs + rhs) { + return lhs + rhs; +} +``` - // No warning - auto lambda = [](double x, double y) -> double {return x + y;}; - - // No warning - template <typename T1, typename T2> - auto fn(const T1 &lhs, const T2 &rhs) -> decltype(lhs + rhs) { - return lhs + rhs; - } - - -See the features disallowed in Fuchsia at https://fuchsia.dev/fuchsia-src/development/languages/c-cpp/cxx +See the features disallowed in Fuchsia at <https://fuchsia.dev/fuchsia-src/development/languages/c-cpp/cxx> _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
