[llvm-branch-commits] [clang-tools-extra] [clang-tidy][docs] Rewrite bugprone check docs to Markdown [4/4] (PR #214427)
Zeyi Xu via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Tue Aug 11 04:51:59 PDT 2026
https://github.com/zeyi2 updated https://github.com/llvm/llvm-project/pull/214427
>From 0435777c4cf4811862b89f4819bcf95a2deef6d5 Mon Sep 17 00:00:00 2001
From: Zeyi Xu <mitchell.xu2 at gmail.com>
Date: Thu, 6 Aug 2026 16:08:44 +0800
Subject: [PATCH] [clang-tidy][docs] Rewrite bugprone check docs to Markdown
[4/4]
---
.../bugprone/suspicious-realloc-usage.md | 56 +-
.../checks/bugprone/suspicious-semicolon.md | 70 ++-
.../bugprone/suspicious-string-compare.md | 92 ++--
.../suspicious-stringview-data-usage.md | 78 ++-
.../checks/bugprone/swapped-arguments.md | 22 +-
.../bugprone/switch-missing-default-case.md | 78 +--
.../bugprone/tagged-union-member-count.md | 480 +++++++++---------
.../bugprone/too-small-loop-variable.md | 72 +--
.../bugprone/unchecked-optional-access.md | 421 ++++++++-------
.../unchecked-string-to-number-conversion.md | 38 +-
.../bugprone/undefined-memory-manipulation.md | 34 +-
.../checks/bugprone/unhandled-code-paths.md | 91 ++--
.../bugprone/unhandled-exception-at-new.md | 81 ++-
.../bugprone/unhandled-self-assignment.md | 178 ++++---
.../unintended-char-ostream-output.md | 86 ++--
.../bugprone/unique-ptr-array-mismatch.md | 47 +-
.../checks/bugprone/unsafe-functions.md | 345 +++++++------
.../bugprone/unsafe-to-allow-exceptions.md | 45 +-
.../unused-local-non-trivial-variable.md | 102 ++--
.../clang-tidy/checks/bugprone/unused-raii.md | 20 +-
.../checks/bugprone/unused-return-value.md | 111 ++--
.../checks/bugprone/use-after-move.md | 326 ++++++------
22 files changed, 1416 insertions(+), 1457 deletions(-)
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-realloc-usage.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-realloc-usage.md
index 9885d9c2ae9ff..5ccd94ec71b90 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-realloc-usage.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-realloc-usage.md
@@ -1,45 +1,45 @@
-.. title:: clang-tidy - bugprone-suspicious-realloc-usage
+```{title} clang-tidy - bugprone-suspicious-realloc-usage
+```
-bugprone-suspicious-realloc-usage
-=================================
+# bugprone-suspicious-realloc-usage
-This check finds usages of ``realloc`` where the return value is assigned to
+This check finds usages of `realloc` where the return value is assigned to
the same expression as passed to the first argument:
-``p = realloc(p, size);``
-The problem with this construct is that if ``realloc`` fails it returns a
+`p = realloc(p, size);`
+The problem with this construct is that if `realloc` fails it returns a
null pointer but does not deallocate the original memory. If no other variable
is pointing to it, the original memory block is not available any more for the
-program to use or free. In either case ``p = realloc(p, size);`` indicates bad
-coding style and can be replaced by ``q = realloc(p, size);``.
+program to use or free. In either case `p = realloc(p, size);` indicates bad
+coding style and can be replaced by `q = realloc(p, size);`.
-The pointer expression (used at ``realloc``) can be a variable or a field
+The pointer expression (used at `realloc`) can be a variable or a field
member of a data structure, but can not contain function calls or unresolved
types.
In obvious cases when the pointer used at realloc is assigned to another
-variable before the ``realloc`` call, no warning is emitted. This happens only
-if a simple expression in form of ``q = p`` or ``void *q = p`` is found in the
-same function where ``p = realloc(p, ...)`` is found. The assignment has to be
+variable before the `realloc` call, no warning is emitted. This happens only
+if a simple expression in form of `q = p` or `void *q = p` is found in the
+same function where `p = realloc(p, ...)` is found. The assignment has to be
before the call to realloc (but otherwise at any place) in the same function.
-This suppression works only if ``p`` is a single variable.
+This suppression works only if `p` is a single variable.
Examples:
-.. code-block:: c++
+```c++
+struct A {
+ void *p;
+};
- struct A {
- void *p;
- };
+A &getA();
- A &getA();
+void foo(void *p, A *a, int new_size) {
+ p = realloc(p, new_size); // warning: 'p' may be set to null if 'realloc' fails, which may result in a leak of the original buffer
+ a->p = realloc(a->p, new_size); // warning: 'a->p' may be set to null if 'realloc' fails, which may result in a leak of the original buffer
+ getA().p = realloc(getA().p, new_size); // no warning
+}
- void foo(void *p, A *a, int new_size) {
- p = realloc(p, new_size); // warning: 'p' may be set to null if 'realloc' fails, which may result in a leak of the original buffer
- a->p = realloc(a->p, new_size); // warning: 'a->p' may be set to null if 'realloc' fails, which may result in a leak of the original buffer
- getA().p = realloc(getA().p, new_size); // no warning
- }
-
- void foo1(void *p, int new_size) {
- void *p1 = p;
- p = realloc(p, new_size); // no warning
- }
+void foo1(void *p, int new_size) {
+ void *p1 = p;
+ p = realloc(p, new_size); // no warning
+}
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-semicolon.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-semicolon.md
index 56e23d77024cb..f2a015d7b3d11 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-semicolon.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-semicolon.md
@@ -1,39 +1,37 @@
-.. title:: clang-tidy - bugprone-suspicious-semicolon
+```{title} clang-tidy - bugprone-suspicious-semicolon
+```
-bugprone-suspicious-semicolon
-=============================
+# bugprone-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 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++
+```c++
+if (x < y);
+{
+ x++;
+}
+```
- if (x < y);
- {
- x++;
- }
-
-Here the body of the ``if`` statement consists of only the semicolon at the end
+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);
+```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
+`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;
+```c++
+if (x >= y);
+x -= y;
+```
While the indentation does not imply any nesting, there is simply no valid
reason to have an `if` statement with an empty body (but it can make sense for
@@ -43,10 +41,10 @@ To solve the issue remove the stray semicolon or in case the empty body is
intentional, reflect this using code indentation or put the semicolon in a new
line. For example:
-.. code-block:: c++
-
- while (readWhitespace());
- Token t = readNextToken();
+```c++
+while (readWhitespace());
+ Token t = readNextToken();
+```
Here the second line is indented in a way that suggests that it is meant to be
the body of the `while` loop - whose body is in fact empty, because of the
@@ -54,19 +52,19 @@ semicolon at the end of the first line.
Either remove the indentation from the second line:
-.. code-block:: c++
-
- while (readWhitespace());
- Token t = readNextToken();
+```c++
+while (readWhitespace());
+Token t = readNextToken();
+```
... or move the semicolon from the end of the first line to a new line:
-.. code-block:: c++
-
- while (readWhitespace())
- ;
+```c++
+while (readWhitespace())
+ ;
- Token t = readNextToken();
+ Token t = readNextToken();
+```
In this case the check will assume that you know what you are doing, and will
not raise a warning.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-string-compare.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-string-compare.md
index 973b70393faf0..8ad74ff49725a 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-string-compare.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-string-compare.md
@@ -1,64 +1,64 @@
-.. title:: clang-tidy - bugprone-suspicious-string-compare
+```{title} clang-tidy - bugprone-suspicious-string-compare
+```
-bugprone-suspicious-string-compare
-==================================
+# bugprone-suspicious-string-compare
Find suspicious usage of runtime string comparison functions.
This check is valid in C and C++.
Checks for calls with implicit comparator and proposed to explicitly add it.
-.. code-block:: c++
+```c++
+if (strcmp(...)) // Implicitly compare to zero
+if (!strcmp(...)) // Won't warn
+if (strcmp(...) != 0) // Won't warn
+```
- if (strcmp(...)) // Implicitly compare to zero
- if (!strcmp(...)) // Won't warn
- if (strcmp(...) != 0) // Won't warn
-
-Checks that compare function results (i.e., ``strcmp``) are compared to valid
+Checks that compare function results (i.e., `strcmp`) are compared to valid
constant. The resulting value is
-.. code::
-
- < 0 when lower than,
- > 0 when greater than,
- == 0 when equals.
+```
+< 0 when lower than,
+> 0 when greater than,
+== 0 when equals.
+```
A common mistake is to compare the result to `1` or `-1`.
-.. code-block:: c++
-
- if (strcmp(...) == -1) // Incorrect usage of the returned value.
+```c++
+if (strcmp(...) == -1) // Incorrect usage of the returned value.
+```
Additionally, the check warns if the results value is implicitly cast to a
*suspicious* non-integer type. It's happening when the returned value is
used in a wrong context.
-.. code-block:: c++
-
- if (strcmp(...) < 0.) // Incorrect usage of the returned value.
-
-Options
--------
-
-.. option:: WarnOnImplicitComparison
-
- When `true`, the check will warn on implicit comparison. `true` by default.
-
-.. option:: WarnOnLogicalNotComparison
-
- When `true`, the check will warn on logical not comparison. `false` by default.
-
-.. option:: StringCompareLikeFunctions
-
- A string specifying the comma-separated names of the extra string comparison
- functions. Default is an empty string.
- The check will detect the following string comparison functions:
- `__builtin_memcmp`, `__builtin_strcasecmp`, `__builtin_strcmp`,
- `__builtin_strncasecmp`, `__builtin_strncmp`, `_mbscmp`, `_mbscmp_l`,
- `_mbsicmp`, `_mbsicmp_l`, `_mbsnbcmp`, `_mbsnbcmp_l`, `_mbsnbicmp`,
- `_mbsnbicmp_l`, `_mbsncmp`, `_mbsncmp_l`, `_mbsnicmp`, `_mbsnicmp_l`,
- `_memicmp`, `_memicmp_l`, `_stricmp`, `_stricmp_l`, `_strnicmp`,
- `_strnicmp_l`, `_wcsicmp`, `_wcsicmp_l`, `_wcsnicmp`, `_wcsnicmp_l`,
- `lstrcmp`, `lstrcmpi`, `memcmp`, `memicmp`, `strcasecmp`, `strcmp`,
- `strcmpi`, `stricmp`, `strncasecmp`, `strncmp`, `strnicmp`, `wcscasecmp`,
- `wcscmp`, `wcsicmp`, `wcsncmp`, `wcsnicmp`, `wmemcmp`.
+```c++
+if (strcmp(...) < 0.) // Incorrect usage of the returned value.
+```
+
+The check will detect the following string comparison functions:
+`__builtin_memcmp`, `__builtin_strcasecmp`, `__builtin_strcmp`,
+`__builtin_strncasecmp`, `__builtin_strncmp`, `_mbscmp`, `_mbscmp_l`,
+`_mbsicmp`, `_mbsicmp_l`, `_mbsnbcmp`, `_mbsnbcmp_l`, `_mbsnbicmp`,
+`_mbsnbicmp_l`, `_mbsncmp`, `_mbsncmp_l`, `_mbsnicmp`, `_mbsnicmp_l`,
+`_memicmp`, `_memicmp_l`, `_stricmp`, `_stricmp_l`, `_strnicmp`,
+`_strnicmp_l`, `_wcsicmp`, `_wcsicmp_l`, `_wcsnicmp`, `_wcsnicmp_l`,
+`lstrcmp`, `lstrcmpi`, `memcmp`, `memicmp`, `strcasecmp`, `strcmp`,
+`strcmpi`, `stricmp`, `strncasecmp`, `strncmp`, `strnicmp`, `wcscasecmp`,
+`wcscmp`, `wcsicmp`, `wcsncmp`, `wcsnicmp`, `wmemcmp`.
+
+## Options
+
+```{option} WarnOnImplicitComparison
+When `true`, the check will warn on implicit comparison. Default is `true`.
+```
+
+```{option} WarnOnLogicalNotComparison
+When `true`, the check will warn on logical not comparison. Default is `false`.
+```
+
+```{option} StringCompareLikeFunctions
+A string specifying the comma-separated names of the extra string comparison
+functions. Default is an empty string.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-stringview-data-usage.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-stringview-data-usage.md
index de10da21e8442..4488eb4c29cfd 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-stringview-data-usage.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-stringview-data-usage.md
@@ -1,61 +1,59 @@
-.. title:: clang-tidy - bugprone-suspicious-stringview-data-usage
+```{title} clang-tidy - bugprone-suspicious-stringview-data-usage
+```
-bugprone-suspicious-stringview-data-usage
-=========================================
+# bugprone-suspicious-stringview-data-usage
-Identifies suspicious usages of ``std::string_view::data()`` that could lead to
+Identifies suspicious usages of `std::string_view::data()` that could lead to
reading out-of-bounds data due to inadequate or incorrect string null
termination.
-It warns when the result of ``data()`` is passed to a constructor or function
-without also passing the corresponding result of ``size()`` or ``length()``
+It warns when the result of `data()` is passed to a constructor or function
+without also passing the corresponding result of `size()` or `length()`
member function. Such usage can lead to unintended behavior, particularly when
-assuming the data pointed to by ``data()`` is null-terminated.
+assuming the data pointed to by `data()` is null-terminated.
-The absence of a ``c_str()`` method in ``std::string_view`` often leads
-developers to use ``data()`` as a substitute, especially when interfacing with
-C APIs that expect null-terminated strings. However, since ``data()`` does not
+The absence of a `c_str()` method in `std::string_view` often leads
+developers to use `data()` as a substitute, especially when interfacing with
+C APIs that expect null-terminated strings. However, since `data()` does not
guarantee null termination, this can result in unintended behavior if the API
relies on proper null termination for correct string interpretation.
In today's programming landscape, this scenario can occur when implicitly
-converting an ``std::string_view`` to an ``std::string``. Since the constructor
-in ``std::string`` designed for string-view-like objects is ``explicit``,
-attempting to pass an ``std::string_view`` to a function expecting an
-``std::string`` will result in a compilation error. As a workaround, developers
-may be tempted to utilize the ``.data()`` method to achieve compilation,
+converting an `std::string_view` to an `std::string`. Since the constructor
+in `std::string` designed for string-view-like objects is `explicit`,
+attempting to pass an `std::string_view` to a function expecting an
+`std::string` will result in a compilation error. As a workaround, developers
+may be tempted to utilize the `.data()` method to achieve compilation,
introducing potential risks.
For instance:
-.. code-block:: c++
+```c++
+void printString(const std::string& str) {
+ std::cout << "String: " << str << std::endl;
+}
- void printString(const std::string& str) {
- std::cout << "String: " << str << std::endl;
- }
+void something(std::string_view sv) {
+ printString(sv.data());
+}
+```
- void something(std::string_view sv) {
- printString(sv.data());
- }
-
-In this example, directly passing ``sv`` to the ``printString`` function would
-lead to a compilation error due to the explicit nature of the ``std::string``
-constructor. Consequently, developers might opt for ``sv.data()`` to resolve the
+In this example, directly passing `sv` to the `printString` function would
+lead to a compilation error due to the explicit nature of the `std::string`
+constructor. Consequently, developers might opt for `sv.data()` to resolve the
compilation error, albeit introducing potential hazards as discussed.
-Options
--------
-
-.. option:: StringViewTypes
-
- Option allows users to specify custom string view-like types for analysis. It
- accepts a semicolon-separated list of type names or regular expressions
- matching these types. Default value is:
- `::std::basic_string_view;::llvm::StringRef`.
+## Options
-.. option:: AllowedCallees
+```{option} StringViewTypes
+Option allows users to specify custom string view-like types for analysis. It
+accepts a semicolon-separated list of type names or regular expressions
+matching these types. Default value is `::std::basic_string_view;::llvm::StringRef`.
+```
- Specifies methods, functions, or classes where the result of ``.data()`` is
- passed to. Allows to exclude such calls from the analysis. Accepts a
- semicolon-separated list of names or regular expressions matching these
- entities. Default value is: empty string.
+```{option} AllowedCallees
+Specifies methods, functions, or classes where the result of `.data()` is
+passed to. Allows to exclude such calls from the analysis. Accepts a
+semicolon-separated list of names or regular expressions matching these
+entities. Default value is empty string.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/swapped-arguments.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/swapped-arguments.md
index e798b67937170..f912ed3deedc1 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/swapped-arguments.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/swapped-arguments.md
@@ -1,7 +1,7 @@
-.. title:: clang-tidy - bugprone-swapped-arguments
+```{title} clang-tidy - bugprone-swapped-arguments
+```
-bugprone-swapped-arguments
-==========================
+# bugprone-swapped-arguments
Finds potentially swapped arguments by examining implicit conversions.
It analyzes the types of the arguments being passed to a function and compares
@@ -9,15 +9,15 @@ them to the expected types of the corresponding parameters. If there is a
mismatch or an implicit conversion that indicates a potential swap, a warning
is raised.
-.. code-block:: c++
+```c++
+void printNumbers(int a, float b);
- void printNumbers(int a, float b);
-
- int main() {
- // Swapped arguments: float passed as int, int as float)
- printNumbers(10.0f, 5);
- return 0;
- }
+int main() {
+ // Swapped arguments: float passed as int, int as float)
+ printNumbers(10.0f, 5);
+ return 0;
+}
+```
Covers a wide range of implicit conversions, including:
- User-defined conversions
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/switch-missing-default-case.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/switch-missing-default-case.md
index 0f0e549091f46..e83a726b4e4e7 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/switch-missing-default-case.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/switch-missing-default-case.md
@@ -1,7 +1,7 @@
-.. title:: clang-tidy - bugprone-switch-missing-default-case
+```{title} clang-tidy - bugprone-switch-missing-default-case
+```
-bugprone-switch-missing-default-case
-====================================
+# bugprone-switch-missing-default-case
Ensures that switch statements without default cases are flagged, focuses only
on covering cases with non-enums where the compiler may not issue warnings.
@@ -19,38 +19,40 @@ values, reducing the risk of program errors and unexpected behavior.
Example:
-.. code-block:: c++
-
- // Example 1:
- // warning: switching on non-enum value without default case may not cover all cases
- switch (i) {
- case 0:
- break;
- }
-
- // Example 2:
- enum E { eE1 };
- E e = eE1;
- switch (e) { // no-warning
- case eE1:
- break;
- }
-
- // Example 3:
- int i = 0;
- switch (i) { // no-warning
- case 0:
- break;
- default:
- break;
- }
-
-.. note::
- Enum types are already covered by compiler warnings (comes under -Wswitch)
- when a switch statement does not handle all enum values. This check focuses
- on non-enum types where the compiler warnings may not be present.
-
-.. seealso::
- The `CppCoreGuideline ES.79 <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#res-default>`_
- provide guidelines on switch statements, including the recommendation to
- always provide a default case.
+```c++
+// Example 1:
+// warning: switching on non-enum value without default case may not cover all cases
+switch (i) {
+case 0:
+ break;
+}
+
+// Example 2:
+enum E { eE1 };
+E e = eE1;
+switch (e) { // no-warning
+case eE1:
+ break;
+}
+
+// Example 3:
+int i = 0;
+switch (i) { // no-warning
+case 0:
+ break;
+default:
+ break;
+}
+```
+
+```{note}
+Enum types are already covered by compiler warnings (comes under -Wswitch)
+when a switch statement does not handle all enum values. This check focuses
+on non-enum types where the compiler warnings may not be present.
+```
+
+```{seealso}
+The [CppCoreGuideline ES.79](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#res-default)
+provide guidelines on switch statements, including the recommendation to
+always provide a default case.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/tagged-union-member-count.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/tagged-union-member-count.md
index 5ac5e3240d7a6..89682cdd7daf8 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/tagged-union-member-count.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/tagged-union-member-count.md
@@ -1,7 +1,7 @@
-.. title:: clang-tidy - bugprone-tagged-union-member-count
+```{title} clang-tidy - bugprone-tagged-union-member-count
+```
-bugprone-tagged-union-member-count
-==================================
+# bugprone-tagged-union-member-count
Gives warnings for tagged unions, where the number of tags is
different from the number of data members inside the union.
@@ -10,47 +10,46 @@ A struct or a class is considered to be a tagged union if it has
exactly one union data member and exactly one enum data member and
any number of other data members that are neither unions or enums.
Furthermore, the types of the union and the enum members must
-not come from system header files nor the ``std`` namespace.
+not come from system header files nor the `std` namespace.
Example:
-.. code-block:: c++
-
- enum Tags {
- Tag1,
- Tag2,
- };
-
- struct TaggedUnion { // warning: tagged union has more data members (3) than tags (2)
- enum Tags Kind;
- union {
- int I;
- float F;
- char *Str;
- } Data;
- };
+```c++
+enum Tags {
+ Tag1,
+ Tag2,
+};
+
+struct TaggedUnion { // warning: tagged union has more data members (3) than tags (2)
+ enum Tags Kind;
+ union {
+ int I;
+ float F;
+ char *Str;
+ } Data;
+};
+```
The following example illustrates the exception for unions and enums from
-system header files and the ``std`` namespace.
-
-.. code-block:: c++
+system header files and the `std` namespace.
- #include <pthread.h>
+```c++
+#include <pthread.h>
- struct NotTaggedUnion {
- enum MyEnum { MyEnumConstant1, MyEnumConstant2 } En;
- pthread_mutex_t Mutex;
- };
+struct NotTaggedUnion {
+ enum MyEnum { MyEnumConstant1, MyEnumConstant2 } En;
+ pthread_mutex_t Mutex;
+};
+```
-The ``pthread_mutex_t`` type may be defined as a union behind a ``typedef``,
+The `pthread_mutex_t` type may be defined as a union behind a `typedef`,
in which case the check could mistake this type as a user-defined tagged union.
After all, it has exactly one enum data member and exactly one union data member.
To avoid false-positive cases originating from this, unions and enums from
-system headers and the ``std`` namespace are ignored when pinpointing the
+system headers and the `std` namespace are ignored when pinpointing the
union part and the enum part of a potential user-defined tagged union.
-How enum constants are counted
-------------------------------
+## How enum constants are counted
The main complicating factor when counting the number of enum constants is that
some of them might be auxiliary values that purposefully don't have a
@@ -60,244 +59,247 @@ enum constant or tracks how many enum constants have been declared.
For an illustration:
-.. code-block:: c++
-
- enum TagWithLast {
- Tag1 = 0,
- Tag2 = 1,
- Tag3 = 2,
- LastTag = 2
- };
-
- enum TagWithCounter {
- Tag1, // is 0
- Tag2, // is 1
- Tag3, // is 2
- TagCount, // is 3
- };
+```c++
+enum TagWithLast {
+ Tag1 = 0,
+ Tag2 = 1,
+ Tag3 = 2,
+ LastTag = 2
+};
+
+enum TagWithCounter {
+ Tag1, // is 0
+ Tag2, // is 1
+ Tag3, // is 2
+ TagCount, // is 3
+};
+```
The check counts the number of distinct values among the enum constants and not
the enum constants themselves. This way the enum constants that are essentially
just aliases of other enum constants are not included in the final count.
-Handling of counting enum constants (ones like :code:`TagCount` in the previous
+Handling of counting enum constants (ones like `TagCount` in the previous
code example) is done by decreasing the number of enum values by one if the name
of the last enum constant starts with a prefix or ends with a suffix specified in
-:option:`CountingEnumPrefixes`, :option:`CountingEnumSuffixes` and it's value is
+{option}`CountingEnumPrefixes`, {option}`CountingEnumSuffixes` and it's value is
one less than the total number of distinct values in the enum.
When the final count is adjusted based on this heuristic then a diagnostic note
is emitted that shows which enum constant matched the criteria.
-The heuristic can be disabled entirely (:option:`EnableCountingEnumHeuristic`)
-or configured to follow your naming convention (:option:`CountingEnumPrefixes`,
-:option:`CountingEnumSuffixes`).
-The strings specified in :option:`CountingEnumPrefixes`,
-:option:`CountingEnumSuffixes` are matched case insensitively.
+The heuristic can be disabled entirely ({option}`EnableCountingEnumHeuristic`)
+or configured to follow your naming convention ({option}`CountingEnumPrefixes`,
+{option}`CountingEnumSuffixes`).
+The strings specified in {option}`CountingEnumPrefixes`,
+{option}`CountingEnumSuffixes` are matched case insensitively.
Example counts:
-.. code-block:: c++
-
- // Enum count is 3, because the value 2 is counted only once
- enum TagWithLast {
- Tag1 = 0,
- Tag2 = 1,
- Tag3 = 2,
- LastTag = 2
- };
-
- // Enum count is 3, because TagCount is heuristically excluded
- enum TagWithCounter {
- Tag1, // is 0
- Tag2, // is 1
- Tag3, // is 2
- TagCount, // is 3
- };
-
-
-Options
--------
-
-.. option:: EnableCountingEnumHeuristic
+```c++
+// Enum count is 3, because the value 2 is counted only once
+enum TagWithLast {
+ Tag1 = 0,
+ Tag2 = 1,
+ Tag3 = 2,
+ LastTag = 2
+};
+
+// Enum count is 3, because TagCount is heuristically excluded
+enum TagWithCounter {
+ Tag1, // is 0
+ Tag2, // is 1
+ Tag3, // is 2
+ TagCount, // is 3
+};
+```
+
+## Options
+
+```{option} EnableCountingEnumHeuristic
+```
This option enables or disables the counting enum heuristic.
It uses the prefixes and suffixes specified in the options
-:option:`CountingEnumPrefixes`, :option:`CountingEnumSuffixes` to find counting enum constants by
+{option}`CountingEnumPrefixes`, {option}`CountingEnumSuffixes` to find counting enum constants by
using them for prefix and suffix matching.
-This option is enabled by default.
-
-When :option:`EnableCountingEnumHeuristic` is `false`:
-
-.. code-block:: c++
-
- enum TagWithCounter {
- Tag1,
- Tag2,
- Tag3,
- TagCount,
- };
-
- struct TaggedUnion {
- TagWithCounter Kind;
- union {
- int A;
- long B;
- char *Str;
- float F;
- } Data;
- };
-
-When :option:`EnableCountingEnumHeuristic` is `true`:
-
-.. code-block:: c++
-
- enum TagWithCounter {
- Tag1,
- Tag2,
- Tag3,
- TagCount,
- };
-
- struct TaggedUnion { // warning: tagged union has more data members (4) than tags (3)
- TagWithCounter Kind;
- union {
- int A;
- long B;
- char *Str;
- float F;
- } Data;
- };
-
-.. option:: CountingEnumPrefixes
-
-See :option:`CountingEnumSuffixes` below.
-
-.. option:: CountingEnumSuffixes
-
-CountingEnumPrefixes and CountingEnumSuffixes are lists of semicolon
+Default is `true`.
+
+When {option}`EnableCountingEnumHeuristic` is `false`:
+
+```c++
+enum TagWithCounter {
+ Tag1,
+ Tag2,
+ Tag3,
+ TagCount,
+};
+
+struct TaggedUnion {
+ TagWithCounter Kind;
+ union {
+ int A;
+ long B;
+ char *Str;
+ float F;
+ } Data;
+};
+```
+
+When {option}`EnableCountingEnumHeuristic` is `true`:
+
+```c++
+enum TagWithCounter {
+ Tag1,
+ Tag2,
+ Tag3,
+ TagCount,
+};
+
+struct TaggedUnion { // warning: tagged union has more data members (4) than tags (3)
+ TagWithCounter Kind;
+ union {
+ int A;
+ long B;
+ char *Str;
+ float F;
+ } Data;
+};
+```
+
+```{option} CountingEnumPrefixes
+```
+
+See {option}`CountingEnumSuffixes` below.
+
+```{option} CountingEnumSuffixes
+```
+
+{option}`CountingEnumPrefixes` and {option}`CountingEnumSuffixes` are lists of semicolon
separated strings that are used to search for possible counting enum constants.
These strings are matched case insensitively as prefixes and suffixes
respectively on the names of the enum constants.
-If :option:`EnableCountingEnumHeuristic` is `false` then these options do nothing.
+If {option}`EnableCountingEnumHeuristic` is `false` then these options do nothing.
+
+The default value of {option}`CountingEnumSuffixes` is
+`count` and of
+{option}`CountingEnumPrefixes` is the empty string.
+
+When {option}`EnableCountingEnumHeuristic` is `true` and
+{option}`CountingEnumSuffixes` is `count;size`:
+
+```c++
+enum TagWithCounterCount {
+ Tag1,
+ Tag2,
+ Tag3,
+ TagCount,
+};
+
+struct TaggedUnionCount { // warning: tagged union has more data members (4) than tags (3)
+ TagWithCounterCount Kind;
+ union {
+ int A;
+ long B;
+ char *Str;
+ float F;
+ } Data;
+};
+
+enum TagWithCounterSize {
+ Tag11,
+ Tag22,
+ Tag33,
+ TagSize,
+};
+
+struct TaggedUnionSize { // warning: tagged union has more data members (4) than tags (3)
+ TagWithCounterSize Kind;
+ union {
+ int A;
+ long B;
+ char *Str;
+ float F;
+ } Data;
+};
+```
+
+When {option}`EnableCountingEnumHeuristic` is `true` and
+{option}`CountingEnumPrefixes` is `maxsize;last_`
+
+```c++
+enum TagWithCounterLast {
+ Tag1,
+ Tag2,
+ Tag3,
+ last_tag,
+};
+
+struct TaggedUnionLast { // warning: tagged union has more data members (4) than tags (3)
+ TagWithCounterLast tag;
+ union {
+ int I;
+ short S;
+ char *C;
+ float F;
+ } Data;
+};
+
+enum TagWithCounterMaxSize {
+ Tag1,
+ Tag2,
+ Tag3,
+ MaxSizeTag,
+};
+
+struct TaggedUnionMaxSize { // warning: tagged union has more data members (4) than tags (3)
+ TagWithCounterMaxSize tag;
+ union {
+ int I;
+ short S;
+ char *C;
+ float F;
+ } Data;
+};
+```
+
+```{option} StrictMode
+```
-The default value of :option:`CountingEnumSuffixes` is `count` and of
-:option:`CountingEnumPrefixes` is the empty string.
+When enabled, the check will also give a warning, when the number of tags
+is greater than the number of union data members.
-When :option:`EnableCountingEnumHeuristic` is `true` and
-:option:`CountingEnumSuffixes` is `count;size`:
+Default is `false`.
-.. code-block:: c++
+When {option}`StrictMode` is `false`:
- enum TagWithCounterCount {
+```c++
+struct TaggedUnion {
+ enum {
Tag1,
Tag2,
Tag3,
- TagCount,
- };
-
- struct TaggedUnionCount { // warning: tagged union has more data members (4) than tags (3)
- TagWithCounterCount Kind;
- union {
- int A;
- long B;
- char *Str;
- float F;
- } Data;
- };
-
- enum TagWithCounterSize {
- Tag11,
- Tag22,
- Tag33,
- TagSize,
- };
-
- struct TaggedUnionSize { // warning: tagged union has more data members (4) than tags (3)
- TagWithCounterSize Kind;
- union {
- int A;
- long B;
- char *Str;
- float F;
- } Data;
- };
-
-When :option:`EnableCountingEnumHeuristic` is `true` and
-:option:`CountingEnumPrefixes` is `maxsize;last_`
-
-.. code-block:: c++
-
- enum TagWithCounterLast {
+ } Tags;
+ union {
+ int I;
+ float F;
+ } Data;
+};
+```
+
+When {option}`StrictMode` is `true`:
+
+```c++
+struct TaggedUnion { // warning: tagged union has fewer data members (2) than tags (3)
+ enum {
Tag1,
Tag2,
Tag3,
- last_tag,
- };
-
- struct TaggedUnionLast { // warning: tagged union has more data members (4) than tags (3)
- TagWithCounterLast tag;
- union {
- int I;
- short S;
- char *C;
- float F;
- } Data;
- };
-
- enum TagWithCounterMaxSize {
- Tag1,
- Tag2,
- Tag3,
- MaxSizeTag,
- };
-
- struct TaggedUnionMaxSize { // warning: tagged union has more data members (4) than tags (3)
- TagWithCounterMaxSize tag;
- union {
- int I;
- short S;
- char *C;
- float F;
- } Data;
- };
-
-.. option:: StrictMode
-
-When enabled, the check will also give a warning, when the number of tags
-is greater than the number of union data members.
-
-This option is disabled by default.
-
-When :option:`StrictMode` is `false`:
-
-.. code-block:: c++
-
- struct TaggedUnion {
- enum {
- Tag1,
- Tag2,
- Tag3,
- } Tags;
- union {
- int I;
- float F;
- } Data;
- };
-
-When :option:`StrictMode` is `true`:
-
-.. code-block:: c++
-
- struct TaggedUnion { // warning: tagged union has fewer data members (2) than tags (3)
- enum {
- Tag1,
- Tag2,
- Tag3,
- } Tags;
- union {
- int I;
- float F;
- } Data;
- };
+ } Tags;
+ union {
+ int I;
+ float F;
+ } Data;
+};
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/too-small-loop-variable.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/too-small-loop-variable.md
index efba0ccf97493..5d2bdabf1afe9 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/too-small-loop-variable.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/too-small-loop-variable.md
@@ -1,30 +1,30 @@
-.. title:: clang-tidy - bugprone-too-small-loop-variable
+```{title} clang-tidy - bugprone-too-small-loop-variable
+```
-bugprone-too-small-loop-variable
-================================
+# bugprone-too-small-loop-variable
-Detects those ``for`` loops that have a loop variable with a "too small" type
+Detects those `for` loops that have a loop variable with a "too small" type
which means this type can't represent all values which are part of the
iteration range.
-.. code-block:: c++
+```c++
+int main() {
+ long size = 294967296l;
+ for (short i = 0; i < size; ++i) {}
+}
+```
- int main() {
- long size = 294967296l;
- for (short i = 0; i < size; ++i) {}
- }
-
-This ``for`` loop is an infinite loop because the ``short`` type can't
-represent all values in the ``[0..size]`` interval.
+This `for` loop is an infinite loop because the `short` type can't
+represent all values in the `[0..size]` interval.
In a real use case size means a container's size which depends on the
user input.
-.. code-block:: c++
-
- int doSomething(const std::vector& items) {
- for (short i = 0; i < items.size(); ++i) {}
- }
+```c++
+int doSomething(const std::vector& items) {
+ for (short i = 0; i < items.size(); ++i) {}
+}
+```
This algorithm works for a small amount of objects, but will lead to freeze for
a larger user input.
@@ -34,22 +34,22 @@ It's recommended to enable the compiler warning
not inspect compile-time constant loop boundaries to avoid overlaps with
the warning.
-Options
--------
-
-.. option:: MagnitudeBitsUpperLimit
-
- Upper limit for the magnitude bits of the loop variable. If it's set the check
- filters out those catches in which the loop variable's type has more magnitude
- bits as the specified upper limit. The default value is 16.
- For example, if the user sets this option to 31 (bits), then a 32-bit ``unsigned int``
- is ignored by the check, however a 32-bit ``int`` is not (A 32-bit ``signed int``
- has 31 magnitude bits).
-
-.. code-block:: c++
-
- int main() {
- long size = 294967296l;
- for (unsigned i = 0; i < size; ++i) {} // no warning with MagnitudeBitsUpperLimit = 31 on a system where unsigned is 32-bit
- for (int i = 0; i < size; ++i) {} // warning with MagnitudeBitsUpperLimit = 31 on a system where int is 32-bit
- }
+## Options
+
+```{option} MagnitudeBitsUpperLimit
+Upper limit for the magnitude bits of the loop variable. If it's set the check
+filters out those catches in which the loop variable's type has more magnitude
+bits as the specified upper limit.
+For example, if the user sets this option to 31 (bits), then a 32-bit `unsigned int`
+is ignored by the check, however a 32-bit `int` is not (A 32-bit `signed int`
+has 31 magnitude bits).
+Default value is `16`.
+```
+
+```c++
+int main() {
+ long size = 294967296l;
+ for (unsigned i = 0; i < size; ++i) {} // no warning with MagnitudeBitsUpperLimit = 31 on a system where unsigned is 32-bit
+ for (int i = 0; i < size; ++i) {} // warning with MagnitudeBitsUpperLimit = 31 on a system where int is 32-bit
+}
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unchecked-optional-access.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unchecked-optional-access.md
index 69834270a80f6..5f784f100f244 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unchecked-optional-access.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unchecked-optional-access.md
@@ -1,349 +1,326 @@
-.. title:: clang-tidy - bugprone-unchecked-optional-access
+```{title} clang-tidy - bugprone-unchecked-optional-access
+```
-bugprone-unchecked-optional-access
-==================================
+# bugprone-unchecked-optional-access
*Note*: This check uses a flow-sensitive static analysis to produce its
results. Therefore, it may be more resource intensive (RAM, CPU) than the
average clang-tidy check.
This check identifies unsafe accesses to values contained in
-``std::optional<T>``, ``absl::optional<T>``, ``base::Optional<T>``,
-``folly::Optional<T>``, ``bsl::optional``, or
-``BloombergLP::bdlb::NullableValue`` objects. Below we will refer to all these
-types collectively as ``optional<T>``.
+`std::optional<T>`, `absl::optional<T>`, `base::Optional<T>`,
+`folly::Optional<T>`, `bsl::optional`, or
+`BloombergLP::bdlb::NullableValue` objects. Below we will refer to all these
+types collectively as `optional<T>`.
-An access to the value of an ``optional<T>`` occurs when one of its ``value``,
-``operator*``, or ``operator->`` member functions is invoked. To align with
+An access to the value of an `optional<T>` occurs when one of its `value`,
+`operator*`, or `operator->` member functions is invoked. To align with
common misconceptions, the check considers these member functions as
equivalent, even though there are subtle differences related to exceptions
versus undefined behavior. See *Additional notes*, below, for more information
on this topic.
-An access to the value of an ``optional<T>`` is considered safe if and only if
+An access to the value of an `optional<T>` is considered safe if and only if
code in the local scope (for example, a function body) ensures that the
-``optional<T>`` has a value in all possible execution paths that can reach the
+`optional<T>` has a value in all possible execution paths that can reach the
access. That should happen either through an explicit check, using the
-``optional<T>::has_value`` member function, or by constructing the
-``optional<T>`` in a way that shows that it unambiguously holds a value (e.g
-using ``std::make_optional`` which always returns a populated
-``std::optional<T>``).
+`optional<T>::has_value` member function, or by constructing the
+`optional<T>` in a way that shows that it unambiguously holds a value (e.g
+using `std::make_optional` which always returns a populated
+`std::optional<T>`).
Below we list some examples, starting with unsafe optional access patterns,
followed by safe access patterns.
-Unsafe access patterns
-~~~~~~~~~~~~~~~~~~~~~~
+## Unsafe access patterns
-Access the value without checking if it exists
-----------------------------------------------
+### Access the value without checking if it exists
The check flags accesses to the value that are not locally guarded by
existence check:
-.. code-block:: c++
+```c++
+void f(std::optional<int> opt) {
+ use(*opt); // unsafe: it is unclear whether `opt` has a value.
+}
+```
- void f(std::optional<int> opt) {
- use(*opt); // unsafe: it is unclear whether `opt` has a value.
- }
-
-Access the value in the wrong branch
-------------------------------------
+### Access the value in the wrong branch
The check is aware of the state of an optional object in different
branches of the code. For example:
-.. code-block:: c++
-
- void f(std::optional<int> opt) {
- if (opt.has_value()) {
- } else {
- use(opt.value()); // unsafe: it is clear that `opt` does *not* have a value.
- }
- }
+```c++
+void f(std::optional<int> opt) {
+ if (opt.has_value()) {
+ } else {
+ use(opt.value()); // unsafe: it is clear that `opt` does *not* have a value.
+ }
+}
+```
-Assume a function result to be stable
--------------------------------------
+### Assume a function result to be stable
The check is aware that function results might not be stable. That is,
consecutive calls to the same function might return different values.
For example:
-.. code-block:: c++
-
- void f(Foo foo) {
- if (foo.take().has_value()) {
- use(*foo.take()); // unsafe: it is unclear whether `foo.take()` has a value.
- }
- }
+```c++
+void f(Foo foo) {
+ if (foo.take().has_value()) {
+ use(*foo.take()); // unsafe: it is unclear whether `foo.take()` has a value.
+ }
+}
+```
-Exception: accessor methods
-```````````````````````````
+#### Exception: accessor methods
The check assumes *accessor* methods of a class are stable, with a heuristic to
-determine which methods are accessors. Specifically, parameter-free ``const``
-methods and smart pointer-like APIs (non ``const`` overloads of ``*`` when
-there is a parallel ``const`` overload) are treated as accessors. Note that
+determine which methods are accessors. Specifically, parameter-free `const`
+methods and smart pointer-like APIs (non `const` overloads of `*` when
+there is a parallel `const` overload) are treated as accessors. Note that
this is not guaranteed to be safe -- but, it is widely used (safely) in
-practice. Calls to non ``const`` methods are assumed to modify the state of
+practice. Calls to non `const` methods are assumed to modify the state of
the object and affect the stability of earlier accessor calls.
-Rely on invariants of uncommon APIs
------------------------------------
+### Rely on invariants of uncommon APIs
The check is unaware of invariants of uncommon APIs. For example:
-.. code-block:: c++
+```c++
+void f(Foo foo) {
+ if (foo.HasProperty("bar")) {
+ use(*foo.GetProperty("bar")); // unsafe: it is unclear whether `foo.GetProperty("bar")` has a value.
+ }
+}
+```
- void f(Foo foo) {
- if (foo.HasProperty("bar")) {
- use(*foo.GetProperty("bar")); // unsafe: it is unclear whether `foo.GetProperty("bar")` has a value.
- }
- }
-
-Check if a value exists, then pass the optional to another function
--------------------------------------------------------------------
+### Check if a value exists, then pass the optional to another function
The check relies on local reasoning. The check and value access must
both happen in the same function. An access is considered unsafe even if
the caller of the function performing the access ensures that the
optional has a value. For example:
-.. code-block:: c++
-
- void g(std::optional<int> opt) {
- use(*opt); // unsafe: it is unclear whether `opt` has a value.
- }
+```c++
+void g(std::optional<int> opt) {
+ use(*opt); // unsafe: it is unclear whether `opt` has a value.
+}
- void f(std::optional<int> opt) {
- if (opt.has_value()) {
- g(opt);
- }
- }
+void f(std::optional<int> opt) {
+ if (opt.has_value()) {
+ g(opt);
+ }
+}
+```
-Safe access patterns
-~~~~~~~~~~~~~~~~~~~~
+## Safe access patterns
-Check if a value exists, then access the value
-----------------------------------------------
+### Check if a value exists, then access the value
The check recognizes all straightforward ways for checking if a value
exists and accessing the value contained in an optional object. For
example:
-.. code-block:: c++
-
- void f(std::optional<int> opt) {
- if (opt.has_value()) {
- use(*opt);
- }
- }
+```c++
+void f(std::optional<int> opt) {
+ if (opt.has_value()) {
+ use(*opt);
+ }
+}
+```
-
-Check if a value exists, then access the value from a copy
-----------------------------------------------------------
+### Check if a value exists, then access the value from a copy
The criteria that the check uses is semantic, not syntactic. It
recognizes when a copy of the optional object being accessed is known to
have a value. For example:
-.. code-block:: c++
-
- void f(std::optional<int> opt1) {
- if (opt1.has_value()) {
- std::optional<int> opt2 = opt1;
- use(*opt2);
- }
- }
-
+```c++
+void f(std::optional<int> opt1) {
+ if (opt1.has_value()) {
+ std::optional<int> opt2 = opt1;
+ use(*opt2);
+ }
+}
+```
-Ensure that a value exists using common macros
-----------------------------------------------
+### Ensure that a value exists using common macros
-The check is aware of common macros like ``CHECK`` and ``DCHECK``. Those can be
+The check is aware of common macros like `CHECK` and `DCHECK`. Those can be
used to ensure that an optional object has a value. For example:
-.. code-block:: c++
+```c++
+void f(std::optional<int> opt) {
+ DCHECK(opt.has_value());
+ use(*opt);
+}
+```
- void f(std::optional<int> opt) {
- DCHECK(opt.has_value());
- use(*opt);
- }
-
-Ensure that a value exists, then access the value in a correlated branch
-------------------------------------------------------------------------
+### Ensure that a value exists, then access the value in a correlated branch
The check is aware of correlated branches in the code and can figure out
when an optional object is ensured to have a value on all execution
paths that lead to an access. For example:
-.. code-block:: c++
-
- void f(std::optional<int> opt) {
- bool safe = false;
- if (opt.has_value() && SomeOtherCondition()) {
- safe = true;
- }
- // ... more code...
- if (safe) {
- use(*opt);
- }
- }
-
-Stabilize function results
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+```c++
+void f(std::optional<int> opt) {
+ bool safe = false;
+ if (opt.has_value() && SomeOtherCondition()) {
+ safe = true;
+ }
+ // ... more code...
+ if (safe) {
+ use(*opt);
+ }
+}
+```
+
+## Stabilize function results
Function results are not assumed to be stable across calls, except for
const accessor methods. For more complex accessors (non-const, or depend on
multiple params) it is best to store the result of the function call in a
local variable and use that variable to access the value. For example:
-.. code-block:: c++
+```c++
+void f(Foo foo) {
+ if (const auto& foo_opt = foo.take(); foo_opt.has_value()) {
+ use(*foo_opt);
+ }
+}
+```
- void f(Foo foo) {
- if (const auto& foo_opt = foo.take(); foo_opt.has_value()) {
- use(*foo_opt);
- }
- }
-
-Do not rely on uncommon-API invariants
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+## Do not rely on uncommon-API invariants
When uncommon APIs guarantee that an optional has contents, do not rely on it
-- instead, check explicitly that the optional object has a value. For example:
-.. code-block:: c++
-
- void f(Foo foo) {
- if (const auto& property = foo.GetProperty("bar")) {
- use(*property);
- }
- }
+```c++
+void f(Foo foo) {
+ if (const auto& property = foo.GetProperty("bar")) {
+ use(*property);
+ }
+}
+```
-instead of the `HasProperty`, `GetProperty` pairing we saw above.
+instead of the `HasProperty`, `GetProperty`
+pairing we saw above.
-Do not rely on caller-performed checks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+## Do not rely on caller-performed checks
If you know that all of a function's callers have checked that an optional
argument has a value, either change the function to take the value directly or
check the optional again in the local scope of the callee. For example:
-.. code-block:: c++
-
- void g(int val) {
- use(val);
- }
+```c++
+void g(int val) {
+ use(val);
+}
- void f(std::optional<int> opt) {
- if (opt.has_value()) {
- g(*opt);
- }
- }
+void f(std::optional<int> opt) {
+ if (opt.has_value()) {
+ g(*opt);
+ }
+}
+```
and
-.. code-block:: c++
+```c++
+struct S {
+ std::optional<int> opt;
+ int x;
+};
- struct S {
- std::optional<int> opt;
- int x;
- };
+void g(const S &s) {
+ if (s.opt.has_value() && s.x > 10) {
+ use(*s.opt);
+}
- void g(const S &s) {
- if (s.opt.has_value() && s.x > 10) {
- use(*s.opt);
- }
+void f(S s) {
+ if (s.opt.has_value()) {
+ g(s);
+ }
+}
+```
- void f(S s) {
- if (s.opt.has_value()) {
- g(s);
- }
- }
+## Additional notes
-Additional notes
-~~~~~~~~~~~~~~~~
-
-Aliases created via ``using`` declarations
-------------------------------------------
+### Aliases created via `using` declarations
The check is aware of aliases of optional types that are created via
-``using`` declarations. For example:
-
-.. code-block:: c++
+`using` declarations. For example:
- using OptionalInt = std::optional<int>;
+```c++
+using OptionalInt = std::optional<int>;
- void f(OptionalInt opt) {
- use(opt.value()); // unsafe: it is unclear whether `opt` has a value.
- }
+void f(OptionalInt opt) {
+ use(opt.value()); // unsafe: it is unclear whether `opt` has a value.
+}
+```
-Lambdas
--------
+### Lambdas
The check does not currently report unsafe optional accesses in lambdas.
A future version will expand the scope to lambdas, following the rules
outlined above. It is best to follow the same principles when using
optionals in lambdas.
-Access with ``operator*()`` vs. ``value()``
--------------------------------------------
+### Access with `operator*()` vs. `value()`
-Given that ``value()`` has well-defined behavior (either throwing an exception
-or terminating the program), why treat it the same as ``operator*()`` which
+Given that `value()` has well-defined behavior (either throwing an exception
+or terminating the program), why treat it the same as `operator*()` which
causes undefined behavior (UB)? That is, why is it considered unsafe to access
-an optional with ``value()``, if it's not provably populated with a value? For
-that matter, why is ``CHECK()`` followed by ``operator*()`` any better than
-``value()``, given that they are semantically equivalent (on configurations
+an optional with `value()`, if it's not provably populated with a value? For
+that matter, why is `CHECK()` followed by `operator*()` any better than
+`value()`, given that they are semantically equivalent (on configurations
that disable exceptions)?
The answer is that we assume most users do not realize the difference between
-``value()`` and ``operator*()``. Shifting to ``operator*()`` and some form of
+`value()` and `operator*()`. Shifting to `operator*()` and some form of
explicit value-presence check or explicit program termination has two
advantages:
- * Readability. The check, and any potential side effects like program
- shutdown, are very clear in the code. Separating access from checks can
- actually make the checks more obvious.
-
- * Performance. A single check can cover many or even all accesses within
- scope. This gives the user the best of both worlds -- the safety of a
- dynamic check, but without incurring redundant costs.
+- Readability. The check, and any potential side effects like program
+ shutdown, are very clear in the code. Separating access from checks can
+ actually make the checks more obvious.
+- Performance. A single check can cover many or even all accesses within
+ scope. This gives the user the best of both worlds -- the safety of a
+ dynamic check, but without incurring redundant costs.
-GoogleTest awareness
---------------------
+### GoogleTest awareness
-The check recognizes common macros like ``ASSERT_TRUE`` and ``ASSERT_FALSE``:
+The check recognizes common macros like `ASSERT_TRUE` and `ASSERT_FALSE`:
-.. code-block:: c++
+```c++
+TEST(OptionalTest, CheckValue) {
+ std::optional<int> opt;
+ EXPECT_TRUE(opt.has_value());
+ EXPECT_EQ(opt.value(), 42); // unsafe: EXPECT_TRUE doesn't terminate test.
- TEST(OptionalTest, CheckValue) {
- std::optional<int> opt;
- EXPECT_TRUE(opt.has_value());
- EXPECT_EQ(opt.value(), 42); // unsafe: EXPECT_TRUE doesn't terminate test.
+ ASSERT_TRUE(opt.has_value());
+ EXPECT_EQ(opt.value(), 42); // safe: ASSERT_TRUE terminates if no value.
+}
+```
- ASSERT_TRUE(opt.has_value());
- EXPECT_EQ(opt.value(), 42); // safe: ASSERT_TRUE terminates if no value.
- }
-
-Less common macros such as ``ASSERT_NE(..., nullopt)`` and ``ASSERT_THAT`` are
+Less common macros such as `ASSERT_NE(..., nullopt)` and `ASSERT_THAT` are
not currently supported and are ignored, which may result in false positives.
-Options
--------
-
-.. option:: IgnoreSmartPointerDereference
-
- If set to `true`, the check ignores optionals that
- are reached through overloaded smart-pointer-like dereference (``operator*``,
- ``operator->``) on classes other than the optional type itself. This helps
- avoid false positives where the analysis cannot equate results across such
- calls. This does not cover access through ``operator[]``. Default is `false`.
-
-.. option:: IgnoreValueCalls
-
- If set to `true`, the check does not diagnose calls
- to ``optional::value()``. Diagnostics for ``operator*()`` and
- ``operator->()`` remain enabled. This is useful for codebases that
- intentionally rely on ``value()`` for defined, guarded access while still
- flagging UB-prone operator dereferences. Default is `false`.
+### Options
+
+```{option} IgnoreSmartPointerDereference
+If set to `true`, the check ignores optionals that
+are reached through overloaded smart-pointer-like dereference (`operator*`,
+`operator->`) on classes other than the optional type itself. This helps
+avoid false positives where the analysis cannot equate results across such
+calls. This does not cover access through `operator[]`. Default is `false`.
+```
+
+```{option} IgnoreValueCalls
+If set to `true`, the check does not diagnose calls
+to `optional::value()`. Diagnostics for `operator*()` and
+`operator->()` remain enabled. This is useful for codebases that
+intentionally rely on `value()` for defined, guarded access while still
+flagging UB-prone operator dereferences. Default is `false`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unchecked-string-to-number-conversion.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unchecked-string-to-number-conversion.md
index 31d3262acbeb2..b2f88a41e2034 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unchecked-string-to-number-conversion.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unchecked-string-to-number-conversion.md
@@ -1,31 +1,29 @@
-.. title:: clang-tidy - bugprone-unchecked-string-to-number-conversion
+```{title} clang-tidy - bugprone-unchecked-string-to-number-conversion
+```
-bugprone-unchecked-string-to-number-conversion
-==============================================
+# bugprone-unchecked-string-to-number-conversion
This check flags calls to string-to-number conversion functions that do not
-verify the validity of the conversion, such as ``atoi()`` or ``scanf()``. It
-does not flag calls to ``strtol()``, or other, related conversion functions
+verify the validity of the conversion, such as `atoi()` or `scanf()`. It
+does not flag calls to `strtol()`, or other, related conversion functions
that do perform better error checking.
-.. code-block:: c
+```c
+#include <stdlib.h>
- #include <stdlib.h>
+void func(const char *buff) {
+ int si;
- void func(const char *buff) {
- int si;
-
- if (buff) {
- si = atoi(buff); /* 'atoi' used to convert a string to an integer, but function will
- not report conversion errors; consider using 'strtol' instead. */
- } else {
- /* Handle error */
- }
+ if (buff) {
+ si = atoi(buff); /* 'atoi' used to convert a string to an integer, but function will
+ not report conversion errors; consider using 'strtol' instead. */
+ } else {
+ /* Handle error */
}
+}
+```
-References
-----------
+## References
This check corresponds to the CERT C Coding Standard rule
-`ERR34-C. Detect errors when converting a string to a number
-<https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/error-handling-err/err34-c/>`_.
+[ERR34-C. Detect errors when converting a string to a number](https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/error-handling-err/err34-c/).
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/undefined-memory-manipulation.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/undefined-memory-manipulation.md
index bad1f6d0a8615..41b54e60ee73e 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/undefined-memory-manipulation.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/undefined-memory-manipulation.md
@@ -1,10 +1,10 @@
-.. title:: clang-tidy - bugprone-undefined-memory-manipulation
+```{title} clang-tidy - bugprone-undefined-memory-manipulation
+```
-bugprone-undefined-memory-manipulation
-======================================
+# bugprone-undefined-memory-manipulation
-Finds calls of memory manipulation functions ``memset()``, ``memcpy()`` and
-``memmove()`` on non-TriviallyCopyable objects resulting in undefined behavior.
+Finds calls of memory manipulation functions `memset()`, `memcpy()` and
+`memmove()` on non-TriviallyCopyable objects resulting in undefined behavior.
Using memory manipulation functions on non-TriviallyCopyable objects can lead
to a range of subtle and challenging issues in C++ code. The most immediate
@@ -15,20 +15,20 @@ diagnose the root cause. Additionally, misuse of memory manipulation functions
can bypass essential object-specific operations, such as constructors and
destructors, leading to resource leaks or improper initialization.
-For example, when using ``memcpy`` to copy ``std::string``, pointer data is
+For example, when using `memcpy` to copy `std::string`, pointer data is
being copied, and it can result in a double free issue.
-.. code-block:: c++
+```c++
+#include <cstring>
+#include <string>
- #include <cstring>
- #include <string>
+int main() {
+ std::string source = "Hello";
+ std::string destination;
- int main() {
- std::string source = "Hello";
- std::string destination;
+ std::memcpy(&destination, &source, sizeof(std::string));
- std::memcpy(&destination, &source, sizeof(std::string));
-
- // Undefined behavior may occur here, during std::string destructor call.
- return 0;
- }
+ // Undefined behavior may occur here, during std::string destructor call.
+ return 0;
+}
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-code-paths.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-code-paths.md
index 01208244989c4..c8c374018a03f 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-code-paths.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-code-paths.md
@@ -1,62 +1,61 @@
-.. title:: clang-tidy - bugprone-unhandled-code-paths
+```{title} clang-tidy - bugprone-unhandled-code-paths
+```
-bugprone-unhandled-code-paths
-=============================
+# bugprone-unhandled-code-paths
This check discovers situations where code paths are not fully-covered.
-``if-else if`` chains that miss a final ``else`` branch might lead to
+`if-else if` chains that miss a final `else` branch might lead to
unexpected program execution and be the result of a logical error.
-If the missing ``else`` branch is intended you can leave it empty with
+If the missing `else` branch is intended you can leave it empty with
a clarifying comment.
This warning can be noisy on some code bases, so it is disabled by default.
-.. code-block:: c++
+```c++
+void f1() {
+ int i = determineTheNumber();
- void f1() {
- int i = determineTheNumber();
+ if(i > 0) {
+ // Some Calculation
+ } else if (i < 0) {
+ // Precondition violated or something else.
+ }
+ // ...
+}
+```
- if(i > 0) {
- // Some Calculation
- } else if (i < 0) {
- // Precondition violated or something else.
- }
- // ...
- }
-
-Similar arguments hold for ``switch`` statements which do not cover all
+Similar arguments hold for `switch` statements which do not cover all
possible code paths.
-.. code-block:: c++
-
- // The missing default branch might be a logical error. It can be kept empty
- // if there is nothing to do, making it explicit.
- void f2(int i) {
- switch (i) {
- case 0: // something
- break;
- case 1: // something else
- break;
- }
- // All other numbers?
+```c++
+// The missing default branch might be a logical error. It can be kept empty
+// if there is nothing to do, making it explicit.
+void f2(int i) {
+ switch (i) {
+ case 0: // something
+ break;
+ case 1: // something else
+ break;
}
-
- // Violates this rule as well, but already emits a compiler warning (-Wswitch).
- enum Color { Red, Green, Blue, Yellow };
- void f3(enum Color c) {
- switch (c) {
- case Red: // We can't drive for now.
- break;
- case Green: // We are allowed to drive.
- break;
- }
- // Other cases missing
+ // All other numbers?
+}
+
+// Violates this rule as well, but already emits a compiler warning (-Wswitch).
+enum Color { Red, Green, Blue, Yellow };
+void f3(enum Color c) {
+ switch (c) {
+ case Red: // We can't drive for now.
+ break;
+ case Green: // We are allowed to drive.
+ break;
}
+ // Other cases missing
+}
+```
-Options
--------
-
-.. option:: WarnOnMissingElse
+## Options
- Boolean flag that activates a warning for missing ``else`` branches.
- Default is `false`.
+```{option} WarnOnMissingElse
+Boolean flag that activates a warning for missing `else` branches.
+Default is `false`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-exception-at-new.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-exception-at-new.md
index b818281c8df22..5971eacac692d 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-exception-at-new.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-exception-at-new.md
@@ -1,55 +1,54 @@
-.. title:: clang-tidy - bugprone-unhandled-exception-at-new
+```{title} clang-tidy - bugprone-unhandled-exception-at-new
+```
-bugprone-unhandled-exception-at-new
-===================================
+# bugprone-unhandled-exception-at-new
-Finds calls to ``new`` with missing exception handler for ``std::bad_alloc``.
+Finds calls to `new` with missing exception handler for `std::bad_alloc`.
-Calls to ``new`` may throw exceptions of type ``std::bad_alloc`` that should
-be handled. Alternatively, the nonthrowing form of ``new`` can be
+Calls to `new` may throw exceptions of type `std::bad_alloc` that should
+be handled. Alternatively, the nonthrowing form of `new` can be
used. The check verifies that the exception is handled in the function
-that calls ``new``.
+that calls `new`.
If a nonthrowing version is used or the exception is allowed to propagate out
of the function no warning is generated.
-The exception handler is checked if it catches a ``std::bad_alloc`` or
-``std::exception`` exception type, or all exceptions (catch-all).
-The check assumes that any user-defined ``operator new`` is either
-``noexcept`` or may throw an exception of type ``std::bad_alloc`` (or one
+The exception handler is checked if it catches a `std::bad_alloc` or
+`std::exception` exception type, or all exceptions (catch-all).
+The check assumes that any user-defined `operator new` is either
+`noexcept` or may throw an exception of type `std::bad_alloc` (or one
derived from it). Other exception class types are not taken into account.
-.. code-block:: c++
-
- int *f() noexcept {
- int *p = new int[1000]; // warning: missing exception handler for allocation failure at 'new'
+```c++
+int *f() noexcept {
+ int *p = new int[1000]; // warning: missing exception handler for allocation failure at 'new'
+ // ...
+ return p;
+}
+```
+
+```c++
+int *f1() { // not 'noexcept'
+ int *p = new int[1000]; // no warning: exception can be handled outside
+ // of this function
+ // ...
+ return p;
+}
+
+int *f2() noexcept {
+ try {
+ int *p = new int[1000]; // no warning: exception is handled
// ...
return p;
- }
-
-.. code-block:: c++
-
- int *f1() { // not 'noexcept'
- int *p = new int[1000]; // no warning: exception can be handled outside
- // of this function
+ } catch (std::bad_alloc &) {
// ...
- return p;
}
-
- int *f2() noexcept {
- try {
- int *p = new int[1000]; // no warning: exception is handled
- // ...
- return p;
- } catch (std::bad_alloc &) {
- // ...
- }
- // ...
- }
-
- int *f3() noexcept {
- int *p = new (std::nothrow) int[1000]; // no warning: "nothrow" is used
- // ...
- return p;
- }
-
+ // ...
+}
+
+int *f3() noexcept {
+ int *p = new (std::nothrow) int[1000]; // no warning: "nothrow" is used
+ // ...
+ return p;
+}
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-self-assignment.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-self-assignment.md
index 6c83ccaf7c32f..323e083fbc5de 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-self-assignment.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unhandled-self-assignment.md
@@ -1,10 +1,11 @@
-.. title:: clang-tidy - bugprone-unhandled-self-assignment
+```{title} clang-tidy - bugprone-unhandled-self-assignment
+```
-bugprone-unhandled-self-assignment
-==================================
+# bugprone-unhandled-self-assignment
-`cert-oop54-cpp` redirects here as an alias for this check. For the CERT alias,
-the `WarnOnlyIfThisHasSuspiciousField` option is set to `false`.
+`cert-oop54-cpp` redirects here as an alias for this check. For
+the CERT alias, the {option}`WarnOnlyIfThisHasSuspiciousField` option
+is set to `false`.
Finds user-defined copy assignment operators which do not protect the code
against self-assignment either by checking self-assignment explicitly or
@@ -16,115 +17,112 @@ likely that self-copy assignment breaks the object if the copy assignment
operator was not written with care.
See also:
-`OOP54-CPP. Gracefully handle self-copy assignment
-<https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/object-oriented-programming-oop/oop54-cpp/>`_
+[OOP54-CPP. Gracefully handle self-copy assignment](https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/object-oriented-programming-oop/oop54-cpp/)
A copy assignment operator must prevent that self-copy assignment ruins the
object state. A typical use case is when the class has a pointer field
and the copy assignment operator first releases the pointed object and
then tries to assign it:
-.. code-block:: c++
+```c++
+class T {
+int* p;
- class T {
- int* p;
+public:
+ T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {}
+ ~T() { delete p; }
- public:
- T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {}
- ~T() { delete p; }
+ // ...
- // ...
-
- T& operator=(const T &rhs) {
- delete p;
- p = new int(*rhs.p);
- return *this;
- }
- };
+ T& operator=(const T &rhs) {
+ delete p;
+ p = new int(*rhs.p);
+ return *this;
+ }
+};
+```
There are two common C++ patterns to avoid this problem. The first is
the self-assignment check:
-.. code-block:: c++
-
- class T {
- int* p;
+```c++
+class T {
+int* p;
- public:
- T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {}
- ~T() { delete p; }
+public:
+ T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {}
+ ~T() { delete p; }
- // ...
+ // ...
- T& operator=(const T &rhs) {
- if(this == &rhs)
- return *this;
-
- delete p;
- p = new int(*rhs.p);
+ T& operator=(const T &rhs) {
+ if(this == &rhs)
return *this;
- }
- };
-The second one is the copy-and-swap method when we create a temporary copy
-(using the copy constructor) and then swap this temporary object with ``this``:
+ delete p;
+ p = new int(*rhs.p);
+ return *this;
+ }
+};
+```
-.. code-block:: c++
+The second one is the copy-and-swap method when we create a temporary copy
+(using the copy constructor) and then swap this temporary object with `this`:
- class T {
- int* p;
+```c++
+class T {
+int* p;
- public:
- T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {}
- ~T() { delete p; }
+public:
+ T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {}
+ ~T() { delete p; }
- // ...
+ // ...
- void swap(T &rhs) {
- using std::swap;
- swap(p, rhs.p);
- }
+ void swap(T &rhs) {
+ using std::swap;
+ swap(p, rhs.p);
+ }
- T& operator=(const T &rhs) {
- T(rhs).swap(*this);
- return *this;
- }
- };
+ T& operator=(const T &rhs) {
+ T(rhs).swap(*this);
+ return *this;
+ }
+};
+```
There is a third pattern which is less common. Let's call it the copy-and-move
method when we create a temporary copy (using the copy constructor) and then move
-this temporary object into ``this`` (needs a move assignment operator):
-
-.. code-block:: c++
-
- class T {
- int* p;
-
- public:
- T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {}
- ~T() { delete p; }
-
- // ...
-
- T& operator=(const T &rhs) {
- T t = rhs;
- *this = std::move(t);
- return *this;
- }
-
- T& operator=(T &&rhs) {
- p = rhs.p;
- rhs.p = nullptr;
- return *this;
- }
- };
-
-Options
--------
-
-.. option:: WarnOnlyIfThisHasSuspiciousField
-
- When `true`, the check will warn only if the container class of the copy
- assignment operator has any suspicious fields (pointer, C array and C++ smart
- pointer).
- This option is set to `true` by default.
+this temporary object into `this` (needs a move assignment operator):
+
+```c++
+class T {
+int* p;
+
+public:
+ T(const T &rhs) : p(rhs.p ? new int(*rhs.p) : nullptr) {}
+ ~T() { delete p; }
+
+ // ...
+
+ T& operator=(const T &rhs) {
+ T t = rhs;
+ *this = std::move(t);
+ return *this;
+ }
+
+ T& operator=(T &&rhs) {
+ p = rhs.p;
+ rhs.p = nullptr;
+ return *this;
+ }
+};
+```
+
+## Options
+
+```{option} WarnOnlyIfThisHasSuspiciousField
+When `true`, the check will warn only if the container class of the copy
+assignment operator has any suspicious fields (pointer, C array and C++ smart
+pointer). Default is `true`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unintended-char-ostream-output.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unintended-char-ostream-output.md
index da510c472e039..3e7416a847944 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unintended-char-ostream-output.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unintended-char-ostream-output.md
@@ -1,59 +1,59 @@
-.. title:: clang-tidy - bugprone-unintended-char-ostream-output
+```{title} clang-tidy - bugprone-unintended-char-ostream-output
+```
-bugprone-unintended-char-ostream-output
-=======================================
+# bugprone-unintended-char-ostream-output
-Finds unintended character output from ``unsigned char`` and ``signed char`` to
-an ``ostream``.
+Finds unintended character output from `unsigned char` and `signed char` to
+an `ostream`.
-Normally, when ``unsigned char (uint8_t)`` or ``signed char (int8_t)`` is used,
+Normally, when `unsigned char (uint8_t)` or `signed char (int8_t)` is used,
it is more likely a number than a character. However, when it is passed
-directly to ``std::ostream``'s ``operator<<``, the result is the character
+directly to `std::ostream`'s `operator<<`, the result is the character
output instead of the numeric value. This often contradicts the developer's
intent to print integer values.
-.. code-block:: c++
-
- uint8_t v = 65;
- std::cout << v; // output 'A' instead of '65'
+```c++
+uint8_t v = 65;
+std::cout << v; // output 'A' instead of '65'
+```
The check will suggest casting the value to an appropriate type to indicate the
-intent, by default, it will cast to ``unsigned int`` for ``unsigned char`` and
-``int`` for ``signed char``.
-
-.. code-block:: c++
+intent, by default, it will cast to `unsigned int` for `unsigned char` and
+`int` for `signed char`.
- std::cout << static_cast<unsigned int>(v); // when v is unsigned char
- std::cout << static_cast<int>(v); // when v is signed char
+```c++
+std::cout << static_cast<unsigned int>(v); // when v is unsigned char
+std::cout << static_cast<int>(v); // when v is signed char
+```
-To avoid lengthy cast statements, add prefix ``+`` to the variable can
+To avoid lengthy cast statements, add prefix `+` to the variable can
also suppress warnings because unary expression will promote the value
-to an ``int``.
-
-.. code-block:: c++
+to an `int`.
- std::cout << +v;
+```c++
+std::cout << +v;
+```
Or cast to char to explicitly indicate that output should be a character.
-.. code-block:: c++
-
- std::cout << static_cast<char>(v);
-
-Options
--------
-
-.. option:: AllowedTypes
-
- A semicolon-separated list of type names that will be treated like the ``char``
- type: the check will not report variables declared with with these types or
- explicit cast expressions to these types. Note that this distinguishes type
- aliases from the original type, so specifying e.g. ``unsigned char`` here
- will not suppress reports about ``uint8_t`` even if it is defined as a
- ``typedef`` alias for ``unsigned char``.
- Default is `unsigned char;signed char`.
-
-.. option:: CastTypeName
-
- When `CastTypeName` is specified, the fix-it will use `CastTypeName` as the
- cast target type. Otherwise, fix-it will automatically infer the type.
+```c++
+std::cout << static_cast<char>(v);
+```
+
+## Options
+
+```{option} AllowedTypes
+A semicolon-separated list of type names that will be treated like the `char`
+type: the check will not report variables declared with with these types or
+explicit cast expressions to these types. Note that this distinguishes type
+aliases from the original type, so specifying e.g. `unsigned char` here
+will not suppress reports about `uint8_t` even if it is defined as a
+`typedef` alias for `unsigned char`.
+Default is `unsigned char;signed char`.
+```
+
+```{option} CastTypeName
+When {option}`CastTypeName` is specified, the fix-it will use
+{option}`CastTypeName` as the
+cast target type. Otherwise, fix-it will automatically infer the type.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unique-ptr-array-mismatch.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unique-ptr-array-mismatch.md
index 71a805543e1b9..ac29cb8ce2de4 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unique-ptr-array-mismatch.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unique-ptr-array-mismatch.md
@@ -1,39 +1,38 @@
-.. title:: clang-tidy - bugprone-unique-ptr-array-mismatch
+```{title} clang-tidy - bugprone-unique-ptr-array-mismatch
+```
-bugprone-unique-ptr-array-mismatch
-==================================
+# bugprone-unique-ptr-array-mismatch
Finds initializations of C++ unique pointers to non-array type that are
initialized with an array.
-If a pointer ``std::unique_ptr<T>`` is initialized with a new-expression
-``new T[]`` the memory is not deallocated correctly. A plain ``delete`` is used
-in this case to deallocate the target memory. Instead a ``delete[]`` call is
-needed. A ``std::unique_ptr<T[]>`` uses the correct delete operator. The check
-does not emit warning if an ``unique_ptr`` with user-specified deleter type is
+If a pointer `std::unique_ptr<T>` is initialized with a new-expression
+`new T[]` the memory is not deallocated correctly. A plain `delete` is used
+in this case to deallocate the target memory. Instead a `delete[]` call is
+needed. A `std::unique_ptr<T[]>` uses the correct delete operator. The check
+does not emit warning if an `unique_ptr` with user-specified deleter type is
used.
-The check offers replacement of ``unique_ptr<T>`` to ``unique_ptr<T[]>`` if it
+The check offers replacement of `unique_ptr<T>` to `unique_ptr<T[]>` if it
is used at a single variable declaration (one variable in one statement).
Example:
-.. code-block:: c++
+```c++
+std::unique_ptr<Foo> x(new Foo[10]); // -> std::unique_ptr<Foo[]> x(new Foo[10]);
+// ^ warning: unique pointer to non-array is initialized with array
+std::unique_ptr<Foo> x1(new Foo), x2(new Foo[10]); // no replacement
+// ^ warning: unique pointer to non-array is initialized with array
- std::unique_ptr<Foo> x(new Foo[10]); // -> std::unique_ptr<Foo[]> x(new Foo[10]);
- // ^ warning: unique pointer to non-array is initialized with array
- std::unique_ptr<Foo> x1(new Foo), x2(new Foo[10]); // no replacement
- // ^ warning: unique pointer to non-array is initialized with array
-
- D d;
- std::unique_ptr<Foo, D> x3(new Foo[10], d); // no warning (custom deleter used)
+D d;
+std::unique_ptr<Foo, D> x3(new Foo[10], d); // no warning (custom deleter used)
- struct S {
- std::unique_ptr<Foo> x(new Foo[10]); // no replacement in this case
- // ^ warning: unique pointer to non-array is initialized with array
- };
+struct S {
+ std::unique_ptr<Foo> x(new Foo[10]); // no replacement in this case
+ // ^ warning: unique pointer to non-array is initialized with array
+};
+```
This check partially covers the CERT C++ Coding Standard rule
-`MEM51-CPP. Properly deallocate dynamically allocated resources
-<https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/memory-management-mem/mem51-cpp/>`_
-However, only the ``std::unique_ptr`` case is detected by this check.
+[MEM51-CPP. Properly deallocate dynamically allocated resources](https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/memory-management-mem/mem51-cpp/)
+However, only the `std::unique_ptr` case is detected by this check.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unsafe-functions.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unsafe-functions.md
index 989d637e8ebbe..76ee83efaf28d 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unsafe-functions.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unsafe-functions.md
@@ -1,7 +1,7 @@
-.. title:: clang-tidy - bugprone-unsafe-functions
+```{title} clang-tidy - bugprone-unsafe-functions
+```
-bugprone-unsafe-functions
-=========================
+# bugprone-unsafe-functions
Checks for functions that have safer, more secure replacements available, or
are considered deprecated due to design flaws.
@@ -9,230 +9,229 @@ The check heavily relies on the functions from the
**Annex K.** "Bounds-checking interfaces" of C11.
The check implements the following rules from the CERT C Coding Standard:
- - Recommendation `MSC24-C. Do not use deprecated or obsolescent functions
- <https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/miscellaneous-msc/msc24-c/>`_.
- - Rule `MSC33-C. Do not pass invalid data to the asctime() function
- <https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/miscellaneous-msc/msc33-c/>`_.
-`cert-msc24-c` and `cert-msc33-c` redirect here as aliases of this check.
+- Recommendation [MSC24-C. Do not use deprecated or obsolescent functions](https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/miscellaneous-msc/msc24-c/).
+- Rule [MSC33-C. Do not pass invalid data to the asctime() function](https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/miscellaneous-msc/msc33-c/).
-Unsafe functions
-----------------
+`cert-msc24-c` and `cert-msc33-c` redirect
+here as aliases of this check.
-The following functions are reported if :option:`ReportDefaultFunctions`
+## Unsafe functions
+
+The following functions are reported if {option}`ReportDefaultFunctions`
is enabled.
If *Annex K.* is available, a replacement from *Annex K.* is suggested for the
following functions:
-``asctime``, ``asctime_r``, ``bsearch``, ``ctime``, ``fopen``, ``fprintf``,
-``freopen``, ``fscanf``, ``fwprintf``, ``fwscanf``, ``getenv``, ``gets``,
-``gmtime``, ``localtime``, ``mbsrtowcs``, ``mbstowcs``, ``memcpy``,
-``memmove``, ``memset``, ``printf``, ``qsort``, ``scanf``, ``snprintf``,
-``sprintf``, ``sscanf``, ``strcat``, ``strcpy``, ``strerror``, ``strlen``,
-``strncat``, ``strncpy``, ``strtok``, ``swprintf``, ``swscanf``, ``vfprintf``,
-``vfscanf``, ``vfwprintf``, ``vfwscanf``, ``vprintf``, ``vscanf``,
-``vsnprintf``, ``vsprintf``, ``vsscanf``, ``vswprintf``, ``vswscanf``,
-``vwprintf``, ``vwscanf``, ``wcrtomb``, ``wcscat``, ``wcscpy``,
-``wcslen``, ``wcsncat``, ``wcsncpy``, ``wcsrtombs``, ``wcstok``, ``wcstombs``,
-``wctomb``, ``wmemcpy``, ``wmemmove``, ``wprintf``, ``wscanf``.
+`asctime`, `asctime_r`, `bsearch`, `ctime`, `fopen`, `fprintf`,
+`freopen`, `fscanf`, `fwprintf`, `fwscanf`, `getenv`, `gets`,
+`gmtime`, `localtime`, `mbsrtowcs`, `mbstowcs`, `memcpy`,
+`memmove`, `memset`, `printf`, `qsort`, `scanf`, `snprintf`,
+`sprintf`, `sscanf`, `strcat`, `strcpy`, `strerror`, `strlen`,
+`strncat`, `strncpy`, `strtok`, `swprintf`, `swscanf`, `vfprintf`,
+`vfscanf`, `vfwprintf`, `vfwscanf`, `vprintf`, `vscanf`,
+`vsnprintf`, `vsprintf`, `vsscanf`, `vswprintf`, `vswscanf`,
+`vwprintf`, `vwscanf`, `wcrtomb`, `wcscat`, `wcscpy`,
+`wcslen`, `wcsncat`, `wcsncpy`, `wcsrtombs`, `wcstok`, `wcstombs`,
+`wctomb`, `wmemcpy`, `wmemmove`, `wprintf`, `wscanf`.
If *Annex K.* is not available, replacements are suggested only for the
following functions from the previous list:
- - ``asctime``, ``asctime_r``, suggested replacement: ``strftime``
- - ``gets``, suggested replacement: ``fgets``
+- `asctime`, `asctime_r`, suggested replacement: `strftime`
+- `gets`, suggested replacement: `fgets`
The following functions are always checked, regardless of *Annex K*
availability:
- - ``rewind``, suggested replacement: ``fseek``
- - ``setbuf``, suggested replacement: ``setvbuf``
- - ``std::get_temporary_buffer``, suggested replacement: "plain" allocation
- with ``operator new[]``
+- `rewind`, suggested replacement: `fseek`
+- `setbuf`, suggested replacement: `setvbuf`
+- `std::get_temporary_buffer`, suggested replacement: "plain" allocation
+ with `operator new[]`
-If :option:`ReportMoreUnsafeFunctions` is enabled,
+If {option}`ReportMoreUnsafeFunctions` is enabled,
the following functions are also checked:
- - ``bcmp``, suggested replacement: ``memcmp``
- - ``bcopy``, suggested replacement: ``memcpy_s`` if *Annex K* is available,
- or ``memcpy``
- - ``bzero``, suggested replacement: ``memset_s`` if *Annex K* is available,
- or ``memset``
- - ``getpw``, suggested replacement: ``getpwuid``
- - ``vfork``, suggested replacement: ``posix_spawn``
+- `bcmp`, suggested replacement: `memcmp`
+- `bcopy`, suggested replacement: `memcpy_s` if *Annex K* is available,
+ or `memcpy`
+- `bzero`, suggested replacement: `memset_s` if *Annex K* is available,
+ or `memset`
+- `getpw`, suggested replacement: `getpwuid`
+- `vfork`, suggested replacement: `posix_spawn`
Although mentioned in the associated CERT rules, the following functions are
**ignored** by the check:
-``atof``, ``atoi``, ``atol``, ``atoll``, ``tmpfile``.
+`atof`, `atoi`, `atol`, `atoll`, `tmpfile`.
The availability of *Annex K* is determined based on the following macros:
- - ``__STDC_LIB_EXT1__``: feature macro, which indicates the presence of
- *Annex K. "Bounds-checking interfaces"* in the library implementation
- - ``__STDC_WANT_LIB_EXT1__``: user-defined macro, which indicates that the
- user requests the functions from *Annex K.* to be defined.
+- `__STDC_LIB_EXT1__`: feature macro, which indicates the presence of
+ *Annex K. "Bounds-checking interfaces"* in the library implementation
+- `__STDC_WANT_LIB_EXT1__`: user-defined macro, which indicates that the
+ user requests the functions from *Annex K.* to be defined.
Both macros have to be defined to suggest replacement functions from *Annex K.*
-``__STDC_LIB_EXT1__`` is defined by the library implementation, and
-``__STDC_WANT_LIB_EXT1__`` must be defined to ``1`` by the user **before**
+`__STDC_LIB_EXT1__` is defined by the library implementation, and
+`__STDC_WANT_LIB_EXT1__` must be defined to `1` by the user **before**
including any system headers.
-.. _CustomFunctions:
+(customfunctions)=
-Custom functions
-----------------
+## Custom functions
-The option :option:`CustomFunctions` allows the user to define custom functions
+The option {option}`CustomFunctions` allows the user to define custom functions
to be checked. The format is the following, without newlines:
-.. code::
-
- bugprone-unsafe-functions.CustomFunctions="
- functionRegex1[, replacement1[, reason1]];
- functionRegex2[, replacement2[, reason2]];
- ...
- "
+```
+bugprone-unsafe-functions.CustomFunctions="
+ functionRegex1[, replacement1[, reason1]];
+ functionRegex2[, replacement2[, reason2]];
+ ...
+"
+```
The functions are matched using POSIX extended regular expressions.
-*(Note: The regular expressions do not support negative* ``(?!)`` *matches.)*
+*(Note: The regular expressions do not support negative* `(?!)` *matches.)*
The `reason` is optional and is used to provide additional information about
the reasoning behind the replacement. The default reason is
`is marked as unsafe`.
-If `replacement` is empty, the default text `it should not be used` will be
+If `replacement` is empty, the default text
+`it should not be used` will be
shown instead of the suggestion for a replacement.
-If the `reason` starts with the character `>`, the reason becomes fully
-custom. The default suffix is disabled even if a `replacement` is present,
+If the `reason` starts with the character
+`>`, the reason becomes fully
+custom. The default suffix is disabled even if a
+`replacement` is present,
and only the reason message is shown after the matched function, to allow
better control over the suggestions. (The starting `>` and whitespace
directly after it are trimmed from the message.)
As an example, the following configuration matches only the function
-``original`` in the default namespace. A similar diagnostic can also be printed
+`original` in the default namespace. A similar diagnostic can also be printed
using a fully custom reason.
-.. code:: c
-
- // bugprone-unsafe-functions.CustomFunctions:
- // ^original$, replacement, is deprecated;
- // Using the fully custom message syntax:
- // ^suspicious$,,> should be avoided if possible.
- original(); // warning: function 'original' is deprecated; 'replacement' should be used instead.
- suspicious(); // warning: function 'suspicious' should be avoided if possible.
- ::std::original(); // no-warning
- original_function(); // no-warning
+```c
+// bugprone-unsafe-functions.CustomFunctions:
+// ^original$, replacement, is deprecated;
+// Using the fully custom message syntax:
+// ^suspicious$,,> should be avoided if possible.
+original(); // warning: function 'original' is deprecated; 'replacement' should be used instead.
+suspicious(); // warning: function 'suspicious' should be avoided if possible.
+::std::original(); // no-warning
+original_function(); // no-warning
+```
If the regular expression contains the character `:`, it is matched against
-the qualified name (i.e. ``std::original``), otherwise the regex is matched
-against the unqualified name (``original``). If the regular expression starts
+the qualified name (i.e. `std::original`), otherwise the regex is matched
+against the unqualified name (`original`). If the regular expression starts
with `::` (or `^::`), it is matched against the fully qualified name
-(``::std::original``).
+(`::std::original`).
One of the use cases for fully custom messages is suggesting compiler options
and warning flags:
-.. code:: c
-
- // bugprone-unsafe-functions.CustomFunctions:
- // ^memcpy$,,>is recommended to have compiler hardening using '_FORTIFY_SOURCE';
- // ^printf$,,>is recommended to have the '-Werror=format-security' compiler warning flag;
-
- memcpy(dest, src, 999'999); // warning: function 'memcpy' is recommended to have compiler hardening using '_FORTIFY_SOURCE'
- printf(raw_str); // warning: function 'printf' is recommended to have the '-Werror=format-security' compiler warning flag
-
-.. note::
-
- Fully qualified names can contain template parameters on certain C++ classes,
- but not on C++ functions. Type aliases are resolved before matching.
-
- As an example, the member function ``open`` in the class ``std::ifstream``
- has a fully qualified name of ``::std::basic_ifstream<char>::open``.
-
- The example could also be matched with the regex
- ``::std::basic_ifstream<[^>]*>::open``, which matches all potential template
- parameters, but does not match nested template classes.
-
-Options
--------
-
-.. option:: ReportMoreUnsafeFunctions
-
- When `true`, additional functions from widely used APIs (such as POSIX) are
- added to the list of reported functions.
- See the main documentation of the check for the complete list as to what
- this option enables.
- Default is `true`.
-
-.. option:: ReportDefaultFunctions
-
- When `true`, the check reports the default set of functions.
- Consider changing the setting to false if you only want to see custom
- functions matched via :ref:`custom functions<CustomFunctions>`.
- Default is `true`.
-
-.. option:: CustomFunctions
-
- A semicolon-separated list of custom functions to be matched. A matched
- function contains a regular expression, an optional name of the replacement
- function, and an optional reason, separated by comma. For more information,
- see :ref:`Custom functions<CustomFunctions>`.
-
-Examples
---------
-
-.. code-block:: c++
-
- #ifndef __STDC_LIB_EXT1__
- #error "Annex K is not supported by the current standard library implementation."
- #endif
-
- #define __STDC_WANT_LIB_EXT1__ 1
-
- #include <string.h> // Defines functions from Annex K.
- #include <stdio.h>
-
- enum { BUFSIZE = 32 };
-
- void Unsafe(const char *Msg) {
- static const char Prefix[] = "Error: ";
- static const char Suffix[] = "\n";
- char Buf[BUFSIZE] = {0};
-
- strcpy(Buf, Prefix); // warning: function 'strcpy' is not bounds-checking; 'strcpy_s' should be used instead.
- strcat(Buf, Msg); // warning: function 'strcat' is not bounds-checking; 'strcat_s' should be used instead.
- strcat(Buf, Suffix); // warning: function 'strcat' is not bounds-checking; 'strcat_s' should be used instead.
- if (fputs(buf, stderr) < 0) {
- // error handling
- return;
- }
- }
-
- void UsingSafeFunctions(const char *Msg) {
- static const char Prefix[] = "Error: ";
- static const char Suffix[] = "\n";
- char Buf[BUFSIZE] = {0};
-
- if (strcpy_s(Buf, BUFSIZE, Prefix) != 0) {
- // error handling
- return;
- }
-
- if (strcat_s(Buf, BUFSIZE, Msg) != 0) {
- // error handling
- return;
- }
-
- if (strcat_s(Buf, BUFSIZE, Suffix) != 0) {
- // error handling
- return;
- }
-
- if (fputs(Buf, stderr) < 0) {
- // error handling
- return;
- }
- }
+```c
+// bugprone-unsafe-functions.CustomFunctions:
+// ^memcpy$,,>is recommended to have compiler hardening using '_FORTIFY_SOURCE';
+// ^printf$,,>is recommended to have the '-Werror=format-security' compiler warning flag;
+
+memcpy(dest, src, 999'999); // warning: function 'memcpy' is recommended to have compiler hardening using '_FORTIFY_SOURCE'
+printf(raw_str); // warning: function 'printf' is recommended to have the '-Werror=format-security' compiler warning flag
+```
+
+```{note}
+Fully qualified names can contain template parameters on certain C++ classes,
+but not on C++ functions. Type aliases are resolved before matching.
+
+As an example, the member function `open` in the class `std::ifstream`
+has a fully qualified name of `::std::basic_ifstream<char>::open`.
+
+The example could also be matched with the regex
+`::std::basic_ifstream<[^>]*>::open`, which matches all potential template
+parameters, but does not match nested template classes.
+```
+
+## Options
+
+```{option} ReportMoreUnsafeFunctions
+When `true`, additional functions from widely used APIs (such as POSIX) are
+added to the list of reported functions.
+See the main documentation of the check for the complete list as to what
+this option enables.
+Default is `true`.
+```
+
+```{option} ReportDefaultFunctions
+When `true`, the check reports the default set of functions.
+Consider changing the setting to false if you only want to see custom
+functions matched via {ref}`custom functions<CustomFunctions>`.
+Default is `true`.
+```
+
+```{option} CustomFunctions
+A semicolon-separated list of custom functions to be matched. A matched
+function contains a regular expression, an optional name of the replacement
+function, and an optional reason, separated by comma. For more information,
+see {ref}`Custom functions<CustomFunctions>`.
+```
+
+## Examples
+
+```c++
+#ifndef __STDC_LIB_EXT1__
+#error "Annex K is not supported by the current standard library implementation."
+#endif
+
+#define __STDC_WANT_LIB_EXT1__ 1
+
+#include <string.h> // Defines functions from Annex K.
+#include <stdio.h>
+
+enum { BUFSIZE = 32 };
+
+void Unsafe(const char *Msg) {
+ static const char Prefix[] = "Error: ";
+ static const char Suffix[] = "\n";
+ char Buf[BUFSIZE] = {0};
+
+ strcpy(Buf, Prefix); // warning: function 'strcpy' is not bounds-checking; 'strcpy_s' should be used instead.
+ strcat(Buf, Msg); // warning: function 'strcat' is not bounds-checking; 'strcat_s' should be used instead.
+ strcat(Buf, Suffix); // warning: function 'strcat' is not bounds-checking; 'strcat_s' should be used instead.
+ if (fputs(buf, stderr) < 0) {
+ // error handling
+ return;
+ }
+}
+
+void UsingSafeFunctions(const char *Msg) {
+ static const char Prefix[] = "Error: ";
+ static const char Suffix[] = "\n";
+ char Buf[BUFSIZE] = {0};
+
+ if (strcpy_s(Buf, BUFSIZE, Prefix) != 0) {
+ // error handling
+ return;
+ }
+
+ if (strcat_s(Buf, BUFSIZE, Msg) != 0) {
+ // error handling
+ return;
+ }
+
+ if (strcat_s(Buf, BUFSIZE, Suffix) != 0) {
+ // error handling
+ return;
+ }
+
+ if (fputs(Buf, stderr) < 0) {
+ // error handling
+ return;
+ }
+}
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unsafe-to-allow-exceptions.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unsafe-to-allow-exceptions.md
index 894b1415e83dd..5ce2f56788a74 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unsafe-to-allow-exceptions.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unsafe-to-allow-exceptions.md
@@ -1,41 +1,40 @@
-.. title:: clang-tidy - bugprone-unsafe-to-allow-exceptions
+```{title} clang-tidy - bugprone-unsafe-to-allow-exceptions
+```
-bugprone-unsafe-to-allow-exceptions
-===================================
+# bugprone-unsafe-to-allow-exceptions
Finds functions where throwing exceptions is unsafe but the function is still
marked as potentially throwing. Throwing exceptions from the following
functions can be problematic:
-* Destructors
-* Move constructors
-* Move assignment operators
-* The ``main()`` functions
-* ``swap()`` functions
-* ``iter_swap()`` functions
-* ``iter_move()`` functions
+- Destructors
+- Move constructors
+- Move assignment operators
+- The `main()` functions
+- `swap()` functions
+- `iter_swap()` functions
+- `iter_move()` functions
A destructor throwing an exception may result in undefined behavior, resource
leaks or unexpected termination of the program. Throwing move constructor or
move assignment also may result in undefined behavior or resource leak. The
-``swap()`` operations expected to be non throwing most of the cases and they
-are always possible to implement in a non throwing way. Non throwing ``swap()``
-operations are also used to create move operations. A throwing ``main()``
+`swap()` operations expected to be non throwing most of the cases and they
+are always possible to implement in a non throwing way. Non throwing `swap()`
+operations are also used to create move operations. A throwing `main()`
function also results in unexpected termination.
-The check finds any of these functions if it is marked with ``noexcept(false)``
-or ``throw(exception)``. This would indicate that the function is expected to
+The check finds any of these functions if it is marked with `noexcept(false)`
+or `throw(exception)`. This would indicate that the function is expected to
throw exceptions. Only the presence of these keywords is checked, not if the
function actually throws any exception. To check if the function actually
-throws exception, the check :doc:`bugprone-exception-escape <exception-escape>`
+throws exception, the check {doc}`bugprone-exception-escape <exception-escape>`
can be used (but it does not warn if a function is explicitly marked as
throwing).
-Options
--------
+## Options
-.. option:: CheckedSwapFunctions
-
- Semicolon-separated list of checked swap function names (where throwing
- exceptions is unsafe). These functions are checked if the parameter count is
- at least 1. Default value is `swap;iter_swap;iter_move`.
+```{option} CheckedSwapFunctions
+Semicolon-separated list of checked swap function names (where throwing
+exceptions is unsafe). These functions are checked if the parameter count is
+at least 1. Default value is `swap;iter_swap;iter_move`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-local-non-trivial-variable.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-local-non-trivial-variable.md
index 672eab62b4af6..997976d8bd2b2 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-local-non-trivial-variable.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-local-non-trivial-variable.md
@@ -1,57 +1,59 @@
-.. title:: clang-tidy - bugprone-unused-local-non-trivial-variable
+```{title} clang-tidy - bugprone-unused-local-non-trivial-variable
+```
-bugprone-unused-local-non-trivial-variable
-==========================================
+# bugprone-unused-local-non-trivial-variable
Warns when a local non trivial variable is unused within a function.
The following types of variables are excluded from this check:
-* trivial and trivially copyable
-* references and pointers
-* exception variables in catch clauses
-* static or thread local
-* structured bindings
-* variables with ``[[maybe_unused]]`` attribute
-* name-independent variables
+- trivial and trivially copyable
+- references and pointers
+- exception variables in catch clauses
+- static or thread local
+- structured bindings
+- variables with `[[maybe_unused]]` attribute
+- name-independent variables
This check can be configured to warn on all non-trivial variables by setting
-`IncludeTypes` to `.*`, and excluding specific types using `ExcludeTypes`.
-
-In the this example, `my_lock` would generate a warning that it is unused.
-
-.. code-block:: c++
-
- std::mutex my_lock;
- // my_lock local variable is never used
-
-In the next example, `future2` would generate a warning that it is unused.
-
-.. code-block:: c++
-
- std::future<MyObject> future1;
- std::future<MyObject> future2;
- // ...
- MyObject foo = future1.get();
- // future2 is not used.
-
-Options
--------
-
-.. option:: IncludeTypes
-
- Semicolon-separated list of regular expressions matching types of variables
- to check. By default the following types are checked:
-
- * `::std::.*mutex`
- * `::std::future`
- * `::std::basic_string`
- * `::std::basic_regex`
- * `::std::basic_istringstream`
- * `::std::basic_stringstream`
- * `::std::bitset`
- * `::std::filesystem::path`
-
-.. option:: ExcludeTypes
-
- A semicolon-separated list of regular expressions matching types that are
- excluded from the `IncludeTypes` matches. By default it is an empty list.
+{option}`IncludeTypes` to `.*`, and excluding
+specific types using {option}`ExcludeTypes`.
+
+In the this example, `my_lock` would generate a warning that
+it is unused.
+
+```c++
+std::mutex my_lock;
+// my_lock local variable is never used
+```
+
+In the next example, `future2` would generate a warning that
+it is unused.
+
+```c++
+std::future<MyObject> future1;
+std::future<MyObject> future2;
+// ...
+MyObject foo = future1.get();
+// future2 is not used.
+```
+
+## Options
+
+```{option} IncludeTypes
+Semicolon-separated list of regular expressions matching types of variables
+to check. By default the following types are checked:
+
+- `::std::.*mutex`
+- `::std::future`
+- `::std::basic_string`
+- `::std::basic_regex`
+- `::std::basic_istringstream`
+- `::std::basic_stringstream`
+- `::std::bitset`
+- `::std::filesystem::path`
+```
+
+```{option} ExcludeTypes
+A semicolon-separated list of regular expressions matching types that are
+excluded from the {option}`IncludeTypes` matches. Default is empty string.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-raii.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-raii.md
index f1987c5319dae..e12233aa7e672 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-raii.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-raii.md
@@ -1,20 +1,20 @@
-.. title:: clang-tidy - bugprone-unused-raii
+```{title} clang-tidy - bugprone-unused-raii
+```
-bugprone-unused-raii
-====================
+# bugprone-unused-raii
Finds temporaries that look like RAII objects.
The canonical example for this is a scoped lock.
-.. code-block:: c++
+```c++
+{
+ scoped_lock(&global_mutex);
+ critical_section();
+}
+```
- {
- scoped_lock(&global_mutex);
- critical_section();
- }
-
-The destructor of the scoped_lock is called before the ``critical_section`` is
+The destructor of the scoped_lock is called before the `critical_section` is
entered, leaving it unprotected.
We apply a number of heuristics to reduce the false positive count of this
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-return-value.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-return-value.md
index 725403a6eb818..a7f4be34f6802 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-return-value.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/unused-return-value.md
@@ -1,69 +1,68 @@
-.. title:: clang-tidy - bugprone-unused-return-value
+```{title} clang-tidy - bugprone-unused-return-value
+```
-bugprone-unused-return-value
-============================
+# bugprone-unused-return-value
Warns on unused function return values. The checked functions can be
configured.
Operator overloading with assignment semantics are ignored.
-Options
--------
+## Options
-.. option:: CheckedFunctions
+```{option} CheckedFunctions
+Semicolon-separated list of functions to check.
+This parameter supports regexp. The function is checked if the name
+and scope matches, with any arguments.
+By default the following functions are checked:
+`^::std::async$, ^::std::launder$, ^::std::remove$, ^::std::remove_if$,
+^::std::unique$, ^::std::unique_ptr::release$, ^::std::basic_string::empty$,
+^::std::vector::empty$, ^::std::back_inserter$, ^::std::distance$,
+^::std::find$, ^::std::find_if$, ^::std::inserter$, ^::std::lower_bound$,
+^::std::make_pair$, ^::std::map::count$, ^::std::map::find$,
+^::std::map::lower_bound$, ^::std::multimap::equal_range$,
+^::std::multimap::upper_bound$, ^::std::set::count$, ^::std::set::find$,
+^::std::setfill$, ^::std::setprecision$, ^::std::setw$, ^::std::upper_bound$,
+^::std::vector::at$, ^::bsearch$, ^::ferror$, ^::feof$, ^::isalnum$,
+^::isalpha$, ^::isblank$, ^::iscntrl$, ^::isdigit$, ^::isgraph$, ^::islower$,
+^::isprint$, ^::ispunct$, ^::isspace$, ^::isupper$, ^::iswalnum$,
+^::iswprint$, ^::iswspace$, ^::isxdigit$, ^::memchr$, ^::memcmp$, ^::strcmp$,
+^::strcoll$, ^::strncmp$, ^::strpbrk$, ^::strrchr$, ^::strspn$, ^::strstr$,
+^::wcscmp$, ^::access$, ^::bind$, ^::connect$, ^::difftime$, ^::dlsym$,
+^::fnmatch$, ^::getaddrinfo$, ^::getopt$, ^::htonl$, ^::htons$,
+^::iconv_open$, ^::inet_addr$, isascii$, isatty$, ^::mmap$, ^::newlocale$,
+^::openat$, ^::pathconf$, ^::pthread_equal$, ^::pthread_getspecific$,
+^::pthread_mutex_trylock$, ^::readdir$, ^::readlink$, ^::recvmsg$,
+^::regexec$, ^::scandir$, ^::semget$, ^::setjmp$, ^::shm_open$, ^::shmget$,
+^::sigismember$, ^::strcasecmp$, ^::strsignal$, ^::ttyname$`
- Semicolon-separated list of functions to check.
- This parameter supports regexp. The function is checked if the name
- and scope matches, with any arguments.
- By default the following functions are checked:
- ``^::std::async$, ^::std::launder$, ^::std::remove$, ^::std::remove_if$,
- ^::std::unique$, ^::std::unique_ptr::release$, ^::std::basic_string::empty$,
- ^::std::vector::empty$, ^::std::back_inserter$, ^::std::distance$,
- ^::std::find$, ^::std::find_if$, ^::std::inserter$, ^::std::lower_bound$,
- ^::std::make_pair$, ^::std::map::count$, ^::std::map::find$,
- ^::std::map::lower_bound$, ^::std::multimap::equal_range$,
- ^::std::multimap::upper_bound$, ^::std::set::count$, ^::std::set::find$,
- ^::std::setfill$, ^::std::setprecision$, ^::std::setw$, ^::std::upper_bound$,
- ^::std::vector::at$, ^::bsearch$, ^::ferror$, ^::feof$, ^::isalnum$,
- ^::isalpha$, ^::isblank$, ^::iscntrl$, ^::isdigit$, ^::isgraph$, ^::islower$,
- ^::isprint$, ^::ispunct$, ^::isspace$, ^::isupper$, ^::iswalnum$,
- ^::iswprint$, ^::iswspace$, ^::isxdigit$, ^::memchr$, ^::memcmp$, ^::strcmp$,
- ^::strcoll$, ^::strncmp$, ^::strpbrk$, ^::strrchr$, ^::strspn$, ^::strstr$,
- ^::wcscmp$, ^::access$, ^::bind$, ^::connect$, ^::difftime$, ^::dlsym$,
- ^::fnmatch$, ^::getaddrinfo$, ^::getopt$, ^::htonl$, ^::htons$,
- ^::iconv_open$, ^::inet_addr$, isascii$, isatty$, ^::mmap$, ^::newlocale$,
- ^::openat$, ^::pathconf$, ^::pthread_equal$, ^::pthread_getspecific$,
- ^::pthread_mutex_trylock$, ^::readdir$, ^::readlink$, ^::recvmsg$,
- ^::regexec$, ^::scandir$, ^::semget$, ^::setjmp$, ^::shm_open$, ^::shmget$,
- ^::sigismember$, ^::strcasecmp$, ^::strsignal$, ^::ttyname$``
+- `std::async()`. Not using the return value makes the call synchronous.
+- `std::launder()`. Not using the return value usually means that the
+ function interface was misunderstood by the programmer. Only the returned
+ pointer is "laundered", not the argument.
+- `std::remove()`, `std::remove_if()` and `std::unique()`. The returned
+ iterator indicates the boundary between elements to keep and elements to be
+ removed. Not using the return value means that the information about which
+ elements to remove is lost.
+- `std::unique_ptr::release()`. Not using the return value can lead to
+ resource leaks if the same pointer isn't stored anywhere else. Often,
+ ignoring the `release()` return value indicates that the programmer
+ confused the function with `reset()`.
+- `std::basic_string::empty()` and `std::vector::empty()`. Not using the
+ return value often indicates that the programmer confused the function with
+ `clear()`.
+```
- - ``std::async()``. Not using the return value makes the call synchronous.
- - ``std::launder()``. Not using the return value usually means that the
- function interface was misunderstood by the programmer. Only the returned
- pointer is "laundered", not the argument.
- - ``std::remove()``, ``std::remove_if()`` and ``std::unique()``. The returned
- iterator indicates the boundary between elements to keep and elements to be
- removed. Not using the return value means that the information about which
- elements to remove is lost.
- - ``std::unique_ptr::release()``. Not using the return value can lead to
- resource leaks if the same pointer isn't stored anywhere else. Often,
- ignoring the ``release()`` return value indicates that the programmer
- confused the function with ``reset()``.
- - ``std::basic_string::empty()`` and ``std::vector::empty()``. Not using the
- return value often indicates that the programmer confused the function with
- ``clear()``.
+```{option} CheckedReturnTypes
+Semicolon-separated list of function return types to check.
+By default the following function return types are checked:
+`^::std::error_code$`, `^::std::error_condition$`, `^::std::errc$`,
+`^::std::expected$`, `^::boost::system::error_code$`
+```
-.. option:: CheckedReturnTypes
+```{option} AllowCastToVoid
+Controls whether casting return values to `void` is permitted. Default is `false`.
+```
- Semicolon-separated list of function return types to check.
- By default the following function return types are checked:
- `^::std::error_code$`, `^::std::error_condition$`, `^::std::errc$`,
- `^::std::expected$`, `^::boost::system::error_code$`
-
-.. option:: AllowCastToVoid
-
- Controls whether casting return values to ``void`` is permitted. Default: `false`.
-
-:doc:`cert-err33-c <../cert/err33-c>` is an alias of this check that checks a
+{doc}`cert-err33-c <../cert/err33-c>` is an alias of this check that checks a
fixed and large set of standard library functions.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/use-after-move.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/use-after-move.md
index 4e746b2633c07..e766283c77ca8 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/use-after-move.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/use-after-move.md
@@ -1,28 +1,28 @@
-.. title:: clang-tidy - bugprone-use-after-move
+```{title} clang-tidy - bugprone-use-after-move
+```
-bugprone-use-after-move
-=======================
+# bugprone-use-after-move
Warns if an object is used after it has been moved, for example:
-.. code-block:: c++
+```c++
+std::string str = "Hello, world!\n";
+std::vector<std::string> messages;
+messages.emplace_back(std::move(str));
+std::cout << str;
+```
- std::string str = "Hello, world!\n";
- std::vector<std::string> messages;
- messages.emplace_back(std::move(str));
- std::cout << str;
-
-The last line will trigger a warning that ``str`` is used after it has been
+The last line will trigger a warning that `str` is used after it has been
moved.
The check does not trigger a warning if the object is reinitialized after the
move and before the use. For example, no warning will be output for this code:
-.. code-block:: c++
-
- messages.emplace_back(std::move(str));
- str = "Greetings, stranger!\n";
- std::cout << str;
+```c++
+messages.emplace_back(std::move(str));
+str = "Greetings, stranger!\n";
+std::cout << str;
+```
Subsections below explain more precisely what exactly the check considers to be
a move, use, and reinitialization.
@@ -31,96 +31,93 @@ The check takes control flow into account. A warning is only emitted if the use
can be reached from the move. This means that the following code does not
produce a warning:
-.. code-block:: c++
-
- if (condition) {
- messages.emplace_back(std::move(str));
- } else {
- std::cout << str;
- }
+```c++
+if (condition) {
+ messages.emplace_back(std::move(str));
+} else {
+ std::cout << str;
+}
+```
On the other hand, the following code does produce a warning:
-.. code-block:: c++
-
- for (int i = 0; i < 10; ++i) {
- std::cout << str;
- messages.emplace_back(std::move(str));
- }
+```c++
+for (int i = 0; i < 10; ++i) {
+ std::cout << str;
+ messages.emplace_back(std::move(str));
+}
+```
(The use-after-move happens on the second iteration of the loop.)
In some cases, the check may not be able to detect that two branches are
-mutually exclusive. For example (assuming that ``i`` is an int):
-
-.. code-block:: c++
+mutually exclusive. For example (assuming that `i` is an int):
- if (i == 1) {
- messages.emplace_back(std::move(str));
- }
- if (i == 2) {
- std::cout << str;
- }
+```c++
+if (i == 1) {
+ messages.emplace_back(std::move(str));
+}
+if (i == 2) {
+ std::cout << str;
+}
+```
In this case, the check will erroneously produce a warning, even though it is
not possible for both the move and the use to be executed. More formally, the
-analysis is `flow-sensitive but not path-sensitive
-<https://en.wikipedia.org/wiki/Data-flow_analysis#Sensitivities>`_.
+analysis is [flow-sensitive but not path-sensitive](https://en.wikipedia.org/wiki/Data-flow_analysis#Sensitivities).
-Silencing erroneous warnings
-----------------------------
+## Silencing erroneous warnings
An erroneous warning can be silenced by reinitializing the object after the
move:
-.. code-block:: c++
-
- if (i == 1) {
- messages.emplace_back(std::move(str));
- str = "";
- }
- if (i == 2) {
- std::cout << str;
- }
+```c++
+if (i == 1) {
+ messages.emplace_back(std::move(str));
+ str = "";
+}
+if (i == 2) {
+ std::cout << str;
+}
+```
If you want to avoid the overhead of actually reinitializing the object,
you can create a dummy function that causes the check to assume the object
was reinitialized:
-.. code-block:: c++
-
- template <class T>
- void IS_INITIALIZED(T&) {}
+```c++
+template <class T>
+void IS_INITIALIZED(T&) {}
+```
You can use this as follows:
-.. code-block:: c++
-
- if (i == 1) {
- messages.emplace_back(std::move(str));
- }
- if (i == 2) {
- IS_INITIALIZED(str);
- std::cout << str;
- }
+```c++
+if (i == 1) {
+ messages.emplace_back(std::move(str));
+}
+if (i == 2) {
+ IS_INITIALIZED(str);
+ std::cout << str;
+}
+```
The check will not output a warning in this case because passing the object
to a function as a non-const pointer or reference counts as a reinitialization
-(see section `Reinitialization`_ below).
+(see section [Reinitialization](#reinitialization) below).
-Unsequenced moves, uses, and reinitializations
-----------------------------------------------
+## Unsequenced moves, uses, and reinitializations
In many cases, C++ does not make any guarantees about the order in which
sub-expressions of a statement are evaluated. This means that in code like the
following, it is not guaranteed whether the use will happen before or after the
move:
-.. code-block:: c++
-
- void f(int i, std::vector<int> v);
- std::vector<int> v = { 1, 2, 3 };
- f(v[1], std::move(v));
+```c++
+void f(int i, std::vector<int> v);
+std::vector<int> v = { 1, 2, 3 };
+f(v[1], std::move(v));
+```
In this kind of situation, the check will note that the use and move are
unsequenced.
@@ -130,152 +127,145 @@ occur in the same statement as moves or uses. A reinitialization is only
considered to reinitialize a variable if it is guaranteed to be evaluated after
the move and before the use.
-Move
-----
+## Move
-The check currently only considers calls of ``std::move`` on local variables or
+The check currently only considers calls of `std::move` on local variables or
function parameters. It does not check moves of member variables or global
variables.
-Any call of ``std::move`` on a variable is considered to cause a move of that
-variable, even if the result of ``std::move`` is not passed to an rvalue
+Any call of `std::move` on a variable is considered to cause a move of that
+variable, even if the result of `std::move` is not passed to an rvalue
reference parameter.
This means that the check will flag a use-after-move even on a type that does
not define a move constructor or move assignment operator. This is intentional.
-Developers may use ``std::move`` on such a type in the expectation that the
-type will add move semantics in the future. If such a ``std::move`` has the
+Developers may use `std::move` on such a type in the expectation that the
+type will add move semantics in the future. If such a `std::move` has the
potential to cause a use-after-move, we want to warn about it even if the type
does not implement move semantics yet.
-Furthermore, if the result of ``std::move`` *is* passed to an rvalue reference
+Furthermore, if the result of `std::move` *is* passed to an rvalue reference
parameter, this will always be considered to cause a move, even if the function
that consumes this parameter does not move from it, or if it does so only
conditionally. For example, in the following situation, the check will assume
that a move always takes place:
-.. code-block:: c++
-
- std::vector<std::string> messages;
- void f(std::string &&str) {
- // Only remember the message if it isn't empty.
- if (!str.empty()) {
- messages.emplace_back(std::move(str));
- }
- }
- std::string str = "";
- f(std::move(str));
+```c++
+std::vector<std::string> messages;
+void f(std::string &&str) {
+ // Only remember the message if it isn't empty.
+ if (!str.empty()) {
+ messages.emplace_back(std::move(str));
+ }
+}
+std::string str = "";
+f(std::move(str));
+```
The check will assume that the last line causes a move, even though, in this
particular case, it does not. Again, this is intentional.
-There is one special case: A call to ``std::move`` inside a ``try_emplace``
+There is one special case: A call to `std::move` inside a `try_emplace`
call is conservatively assumed not to move. This is to avoid spurious warnings,
-as the check has no way to reason about the ``bool`` returned by ``try_emplace``.
+as the check has no way to reason about the `bool` returned by `try_emplace`.
When analyzing the order in which moves, uses and reinitializations happen (see
-section `Unsequenced moves, uses, and reinitializations`_), the move is assumed
-to occur in whichever function the result of the ``std::move`` is passed to.
+section [Unsequenced moves, uses, and
+reinitializations](#unsequenced-moves-uses-and-reinitializations)), the move is
+assumed
+to occur in whichever function the result of the `std::move` is passed to.
-The check also handles perfect-forwarding with ``std::forward`` so the
+The check also handles perfect-forwarding with `std::forward` so the
following code will also trigger a use-after-move warning.
-.. code-block:: c++
+```c++
+void consume(int);
- void consume(int);
+void f(int&& i) {
+ consume(std::forward<int>(i));
+ consume(std::forward<int>(i)); // use-after-move
+}
+```
- void f(int&& i) {
- consume(std::forward<int>(i));
- consume(std::forward<int>(i)); // use-after-move
- }
-
-Use
----
+## Use
Any occurrence of the moved variable that is not a reinitialization (see below)
or an explicit call to the variable destructor is considered to be a use.
-An exception to this are objects of type ``std::unique_ptr``,
-``std::shared_ptr``, ``std::weak_ptr``, ``std::optional``, and ``std::any``,
-which can be reinitialized via ``reset``. For smart pointers specifically, the
-moved-from objects have a well-defined state of being ``nullptr``s, and only
-``operator*``, ``operator->`` and ``operator[]`` are considered bad accesses as
-they would be dereferencing a ``nullptr``.
+An exception to this are objects of type `std::unique_ptr`,
+`std::shared_ptr`, `std::weak_ptr`, `std::optional`, and `std::any`,
+which can be reinitialized via `reset`. For smart pointers specifically, the
+moved-from objects have a well-defined state of being `nullptr`s, and only
+`operator*`, `operator->` and `operator[]` are considered bad accesses as
+they would be dereferencing a `nullptr`.
User-defined types can be annotated as having the same semantics as standard
-smart pointers with ``[[clang::annotate("clang-tidy",
-"bugprone-use-after-move", "null_after_move")]]``. This expresses that a
+smart pointers with `[[clang::annotate("clang-tidy",
+"bugprone-use-after-move", "null_after_move")]]`. This expresses that a
moved-from object of this type is a null pointer.
If multiple uses occur after a move, only the first of these is flagged.
-Reinitialization
-----------------
+## Reinitialization
The check considers a variable to be reinitialized in the following cases:
- - The variable occurs on the left-hand side of an assignment.
-
- - The variable is passed to a function as a non-const pointer or non-const
- lvalue reference. (It is assumed that the variable may be an out-parameter
- for the function.)
-
- - ``clear()`` or ``assign()`` is called on the variable and the variable is
- of one of the standard container types ``basic_string``, ``vector``,
- ``deque``, ``forward_list``, ``list``, ``set``, ``map``, ``multiset``,
- ``multimap``, ``unordered_set``, ``unordered_map``, ``unordered_multiset``,
- ``unordered_multimap``.
-
- - ``reset()`` is called on the variable and the variable is of type
- ``std::unique_ptr``, ``std::shared_ptr``, ``std::weak_ptr``,
- ``std::optional``, or ``std::any``.
-
- - A member function marked with the ``[[clang::reinitializes]]`` attribute is
- called on the variable.
-
- - The variable is passed as an argument to ``std::tie`` on the left-hand
- side of an assignment (e.g. ``std::tie(a, b) = f(...)``). The tuple
- assignment operator writes back through the stored references, which
- reinitializes each named variable.
+- The variable occurs on the left-hand side of an assignment.
+- The variable is passed to a function as a non-const pointer or non-const
+ lvalue reference. (It is assumed that the variable may be an out-parameter
+ for the function.)
+- `clear()` or `assign()` is called on the variable and the variable is
+ of one of the standard container types `basic_string`, `vector`,
+ `deque`, `forward_list`, `list`, `set`, `map`, `multiset`,
+ `multimap`, `unordered_set`, `unordered_map`, `unordered_multiset`,
+ `unordered_multimap`.
+- `reset()` is called on the variable and the variable is of type
+ `std::unique_ptr`, `std::shared_ptr`, `std::weak_ptr`,
+ `std::optional`, or `std::any`.
+- A member function marked with the `[[clang::reinitializes]]` attribute is
+ called on the variable.
+- The variable is passed as an argument to `std::tie` on the left-hand
+ side of an assignment (e.g. `std::tie(a, b) = f(...)`). The tuple
+ assignment operator writes back through the stored references, which
+ reinitializes each named variable.
If the variable in question is a struct and an individual member variable of
that struct is written to, the check does not consider this to be a
reinitialization -- even if, eventually, all member variables of the struct are
written to. For example:
-.. code-block:: c++
-
- struct S {
- std::string str;
- int i;
- };
- S s = { "Hello, world!\n", 42 };
- S s_other = std::move(s);
- s.str = "Lorem ipsum";
- s.i = 99;
-
-The check will not consider ``s`` to be reinitialized after the last line;
-instead, the line that assigns to ``s.str`` will be flagged as a use-after-move.
+```c++
+struct S {
+ std::string str;
+ int i;
+};
+S s = { "Hello, world!\n", 42 };
+S s_other = std::move(s);
+s.str = "Lorem ipsum";
+s.i = 99;
+```
+
+The check will not consider `s` to be reinitialized after the last line;
+instead, the line that assigns to `s.str` will be flagged as a use-after-move.
This is intentional as this pattern of reinitializing a struct is error-prone.
-For example, if an additional member variable is added to ``S``, it is easy to
+For example, if an additional member variable is added to `S`, it is easy to
forget to add the reinitialization for this additional member. Instead, it is
safer to assign to the entire struct in one go, and this will also avoid the
use-after-move warning.
-Options
--------
-
-.. option:: InvalidationFunctions
-
- A semicolon-separated list of regular expressions matching names of functions
- that cause their first arguments to be invalidated (e.g., closing a handle).
- For member functions, the first argument is considered to be the implicit
- object argument (``this``). Default value is an empty string.
-
-.. option:: ReinitializationFunctions
-
- A semicolon-separated list of regular expressions matching names of functions
- that reinitialize the object. For member functions, the implicit object
- argument (``*this``) is considered to be reinitialized. For non-member or
- static member functions, the first argument is considered to be
- reinitialized. Default value is an empty string.
+## Options
+
+```{option} InvalidationFunctions
+A semicolon-separated list of regular expressions matching names of functions
+that cause their first arguments to be invalidated (e.g., closing a handle).
+For member functions, the first argument is considered to be the implicit
+object argument (`this`). Default value is an empty string.
+```
+
+```{option} ReinitializationFunctions
+A semicolon-separated list of regular expressions matching names of functions
+that reinitialize the object. For member functions, the implicit object
+argument (`*this`) is considered to be reinitialized. For non-member or
+static member functions, the first argument is considered to be
+reinitialized. Default value is an empty string.
+```
More information about the llvm-branch-commits
mailing list