[llvm-branch-commits] [clang-tools-extra] [clang-tidy][docs] Rewrite bugprone check docs to Markdown [3/4] (PR #214422)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Thu Aug 6 00:47:50 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-clang-tidy
Author: Zeyi Xu (zeyi2)
<details>
<summary>Changes</summary>
<sub>Stack created with <a href="https://github.com/github/gh-stack">GitHub Stacks CLI</a> • <a href="https://gh.io/stacks-feedback">Give Feedback 💬</a></sub>
---
Patch is 89.20 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/214422.diff
20 Files Affected:
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/random-generator-seed.md (+24-28)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/raw-memory-call-on-non-trivial-type.md (+24-26)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/redundant-branch-condition.md (+68-69)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/reserved-identifier.md (+26-28)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/return-const-ref-from-parameter.md (+27-29)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/shared-ptr-array-mismatch.md (+21-22)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/signal-handler.md (+58-62)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/signed-char-misuse.md (+80-81)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/sizeof-expression.md (+223-239)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/standalone-empty.md (+22-24)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/std-exception-baseclass.md (+22-22)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/std-namespace-modification.md (+33-35)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/string-constructor.md (+36-37)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/string-integer-assignment.md (+25-25)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/string-literal-with-embedded-nul.md (+17-19)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/stringview-nullptr.md (+40-39)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-enum-usage.md (+56-56)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-memory-comparison.md (+10-14)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-memset-usage.md (+35-36)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-missing-comma.md (+40-41)
``````````diff
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/random-generator-seed.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/random-generator-seed.md
index c789f0fa6b27c..4c90025f8368e 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/random-generator-seed.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/random-generator-seed.md
@@ -1,44 +1,40 @@
-.. title:: clang-tidy - bugprone-random-generator-seed
+```{title} clang-tidy - bugprone-random-generator-seed
+```
-bugprone-random-generator-seed
-==============================
+# bugprone-random-generator-seed
Flags all pseudo-random number engines, engine adaptor
-instantiations and ``srand()`` when initialized or seeded with default
+instantiations and `srand()` when initialized or seeded with default
argument, constant expression or any user-configurable type. Pseudo-random
number engines seeded with a predictable value may cause vulnerabilities
e.g. in security protocols.
Examples:
-.. code-block:: c++
+```c++
+void foo() {
+ std::mt19937 engine1; // Diagnose, always generate the same sequence
+ std::mt19937 engine2(1); // Diagnose
+ engine1.seed(); // Diagnose
+ engine2.seed(1); // Diagnose
- void foo() {
- std::mt19937 engine1; // Diagnose, always generate the same sequence
- std::mt19937 engine2(1); // Diagnose
- engine1.seed(); // Diagnose
- engine2.seed(1); // Diagnose
+ std::time_t t;
+ engine1.seed(std::time(&t)); // Diagnose, system time might be controlled by user
- std::time_t t;
- engine1.seed(std::time(&t)); // Diagnose, system time might be controlled by user
+ int x = atoi(argv[1]);
+ std::mt19937 engine3(x); // Will not warn
+}
+```
- int x = atoi(argv[1]);
- std::mt19937 engine3(x); // Will not warn
- }
+## Options
-Options
--------
+```{option} DisallowedSeedTypes
+A comma-separated list of the type names which are disallowed.
+Default value is `time_t,std::time_t`.
+```
-.. option:: DisallowedSeedTypes
-
- A comma-separated list of the type names which are disallowed.
- Default value is `time_t,std::time_t`.
-
-References
-----------
+## References
This check corresponds to the CERT C++ Coding Standard rules
-`MSC51-CPP. Ensure your random number generator is properly seeded
-<https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/miscellaneous-msc/msc51-cpp/>`_ and
-`MSC32-C. Properly seed pseudorandom number generators
-<https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/miscellaneous-msc/msc32-c/>`_.
+[MSC51-CPP. Ensure your random number generator is properly seeded](https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/miscellaneous-msc/msc51-cpp/) and
+[MSC32-C. Properly seed pseudorandom number generators](https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/miscellaneous-msc/msc32-c/).
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/raw-memory-call-on-non-trivial-type.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/raw-memory-call-on-non-trivial-type.md
index 3385abdc39ab3..c057e2302d2ae 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/raw-memory-call-on-non-trivial-type.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/raw-memory-call-on-non-trivial-type.md
@@ -1,35 +1,33 @@
-.. title:: clang-tidy - bugprone-raw-memory-call-on-non-trivial-type
+```{title} clang-tidy - bugprone-raw-memory-call-on-non-trivial-type
+```
-bugprone-raw-memory-call-on-non-trivial-type
-============================================
+# bugprone-raw-memory-call-on-non-trivial-type
-Flags use of the C standard library functions ``memset``, ``memcpy`` and
-``memcmp`` and similar derivatives on non-trivial types.
+Flags use of the C standard library functions `memset`, `memcpy` and
+`memcmp` and similar derivatives on non-trivial types.
-The check will detect the following functions: ``memset``, ``std::memset``,
-``std::memcpy``, ``memcpy``, ``std::memmove``, ``memmove``, ``std::strcpy``,
-``strcpy``, ``memccpy``, ``stpncpy``, ``strncpy``, ``std::memcmp``, ``memcmp``,
-``std::strcmp``, ``strcmp``, ``strncmp``.
+The check will detect the following functions: `memset`, `std::memset`,
+`std::memcpy`, `memcpy`, `std::memmove`, `memmove`, `std::strcpy`,
+`strcpy`, `memccpy`, `stpncpy`, `strncpy`, `std::memcmp`, `memcmp`,
+`std::strcmp`, `strcmp`, `strncmp`.
-Options
--------
+## Options
-.. option:: MemSetNames
+```{option} MemSetNames
+Specify extra functions to flag that act similarly to `memset`. Specify
+names in a semicolon-delimited list. Default is an empty string.
+```
- Specify extra functions to flag that act similarly to ``memset``. Specify
- names in a semicolon-delimited list. Default is an empty string.
+```{option} MemCpyNames
+Specify extra functions to flag that act similarly to `memcpy`. Specify
+names in a semicolon-delimited list. Default is an empty string.
+```
-.. option:: MemCpyNames
-
- Specify extra functions to flag that act similarly to ``memcpy``. Specify
- names in a semicolon-delimited list. Default is an empty string.
-
-.. option:: MemCmpNames
-
- Specify extra functions to flag that act similarly to ``memcmp``. Specify
- names in a semicolon-delimited list. Default is an empty string.
+```{option} MemCmpNames
+Specify extra functions to flag that act similarly to `memcmp`. Specify
+names in a semicolon-delimited list. Default is an empty string.
+```
This check corresponds to the CERT C++ Coding Standard rule
-`OOP57-CPP. Prefer special member functions and overloaded operators to C
-Standard Library functions
-<https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/object-oriented-programming-oop/oop57-cpp/>`_.
+[OOP57-CPP. Prefer special member functions and overloaded operators to C
+Standard Library functions](https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/object-oriented-programming-oop/oop57-cpp/).
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/redundant-branch-condition.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/redundant-branch-condition.md
index 7a321bd9c0f06..1361990d25a65 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/redundant-branch-condition.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/redundant-branch-condition.md
@@ -1,107 +1,106 @@
-.. title:: clang-tidy - bugprone-redundant-branch-condition
+```{title} clang-tidy - bugprone-redundant-branch-condition
+```
-bugprone-redundant-branch-condition
-===================================
+# bugprone-redundant-branch-condition
-Finds condition variables in nested ``if`` statements that were also checked in
-the outer ``if`` statement and were not changed.
+Finds condition variables in nested `if` statements that were also checked in
+the outer `if` statement and were not changed.
Simple example:
-.. code-block:: c
-
- bool onFire = isBurning();
- if (onFire) {
- if (onFire)
- scream();
- }
+```c
+bool onFire = isBurning();
+if (onFire) {
+ if (onFire)
+ scream();
+}
+```
-Here `onFire` is checked both in the outer ``if`` and the inner ``if``
+Here `onFire` is checked both in the outer `if` and the inner `if`
statement without a possible change between the two checks. The check warns for
-this code and suggests removal of the second checking of variable `onFire`.
+this code and suggests removal of the second checking of variable
+`onFire`.
The checker also detects redundant condition checks if the condition variable
-is an operand of a logical "and" (``&&``) or a logical "or" (``||``) operator:
-
-.. code-block:: c
+is an operand of a logical "and" (`&&`) or a logical "or" (`||`) operator:
- bool onFire = isBurning();
- if (onFire) {
- if (onFire && peopleInTheBuilding > 0)
- scream();
- }
-
-.. code-block:: c
+```c
+bool onFire = isBurning();
+if (onFire) {
+ if (onFire && peopleInTheBuilding > 0)
+ scream();
+}
+```
- bool onFire = isBurning();
- if (onFire) {
- if (onFire || isCollapsing())
- scream();
- }
+```c
+bool onFire = isBurning();
+if (onFire) {
+ if (onFire || isCollapsing())
+ scream();
+}
+```
In the first case (logical "and") the suggested fix is to remove the redundant
-condition variable and keep the other side of the ``&&``. In the second case
-(logical "or") the whole ``if`` is removed similarly to the simple case on the
+condition variable and keep the other side of the `&&`. In the second case
+(logical "or") the whole `if` is removed similarly to the simple case on the
top.
-The condition of the outer ``if`` statement may also be a logical "and"
-(``&&``) expression:
-
-.. code-block:: c
+The condition of the outer `if` statement may also be a logical "and"
+(`&&`) expression:
- bool onFire = isBurning();
- if (onFire && fireFighters < 10) {
- if (someOtherCondition()) {
- if (onFire)
- scream();
- }
+```c
+bool onFire = isBurning();
+if (onFire && fireFighters < 10) {
+ if (someOtherCondition()) {
+ if (onFire)
+ scream();
}
+}
+```
The error is also detected if both the outer statement is a logical "and"
-(``&&``) and the inner statement is a logical "and" (``&&``) or "or" (``||``).
-The inner ``if`` statement does not have to be a direct descendant of the outer
+(`&&`) and the inner statement is a logical "and" (`&&`) or "or" (`||`).
+The inner `if` statement does not have to be a direct descendant of the outer
one.
No error is detected if the condition variable may have been changed between
the two checks:
-.. code-block:: c
-
- bool onFire = isBurning();
- if (onFire) {
- tryToExtinguish(onFire);
- if (onFire && peopleInTheBuilding > 0)
- scream();
- }
+```c
+bool onFire = isBurning();
+if (onFire) {
+ tryToExtinguish(onFire);
+ if (onFire && peopleInTheBuilding > 0)
+ scream();
+}
+```
Every possible change is considered, thus if the condition variable is not
a local variable of the function, it is a volatile or it has an alias (pointer
or reference) then no warning is issued.
+## Limitations
-Limitations
------------
-
-The ``else`` branch is not checked currently for negated condition variable:
+The `else` branch is not checked currently for negated condition variable:
-.. code-block:: c
-
- bool onFire = isBurning();
- if (onFire) {
- scream();
- } else {
- if (!onFire) {
- continueWork();
- }
+```c
+bool onFire = isBurning();
+if (onFire) {
+ scream();
+} else {
+ if (!onFire) {
+ continueWork();
}
+}
+```
The checker currently only detects redundant checking of single condition
variables. More complex expressions are not checked:
-.. code-block:: c
-
+```c
+if (peopleInTheBuilding == 1) {
if (peopleInTheBuilding == 1) {
- if (peopleInTheBuilding == 1) {
- doSomething();
- }
+ doSomething();
}
+}
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/reserved-identifier.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/reserved-identifier.md
index f181659270a84..ddda4bafbba4b 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/reserved-identifier.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/reserved-identifier.md
@@ -1,9 +1,10 @@
-.. title:: clang-tidy - bugprone-reserved-identifier
+```{title} clang-tidy - bugprone-reserved-identifier
+```
-bugprone-reserved-identifier
-============================
+# bugprone-reserved-identifier
-`cert-dcl37-c` and `cert-dcl51-cpp` redirect here as an alias for this check.
+`cert-dcl37-c` and `cert-dcl51-cpp` redirect
+here as an alias for this check.
Checks for usages of identifiers reserved for use by the implementation.
@@ -18,14 +19,14 @@ underscore occurring anywhere.
Violating the naming rules above results in undefined behavior.
-.. code-block:: c++
-
- namespace NS {
- void __f(); // name is not allowed in user code
- using _Int = int; // same with this
- #define cool__macro // also this
- }
- int _g(); // disallowed in global namespace only
+```c++
+namespace NS {
+ void __f(); // name is not allowed in user code
+ using _Int = int; // same with this
+ #define cool__macro // also this
+}
+int _g(); // disallowed in global namespace only
+```
The check can also be inverted, i.e. it can be configured to flag any
identifier that is *not* a reserved identifier. This mode is for use by e.g.
@@ -36,22 +37,19 @@ This check does not (yet) check for other reserved names, e.g. macro names
identical to language keywords, and names specifically reserved by language
standards, e.g. C++ 'zombie names' and C future library directions.
-This check corresponds to CERT C Coding Standard rule `DCL37-C. Do not declare
-or define a reserved identifier
-<https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/declarations-and-initialization-dcl/dcl37-c/>`_
-as well as its C++ counterpart, `DCL51-CPP. Do not declare or define a reserved
-identifier
-<https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/declarations-and-initialization-dcl/dcl51-cpp/>`_.
-
-Options
--------
-
-.. option:: Invert
+This check corresponds to CERT C Coding Standard rule [DCL37-C. Do not declare
+or define a reserved identifier](https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/declarations-and-initialization-dcl/dcl37-c/)
+as well as its C++ counterpart, [DCL51-CPP. Do not declare or define a reserved
+identifier](https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/declarations-and-initialization-dcl/dcl51-cpp/).
- If `true`, inverts the check, i.e. flags names that are not reserved.
- Default is `false`.
+## Options
-.. option:: AllowedIdentifiers
+```{option} Invert
+If `true`, inverts the check, i.e. flags names that are not reserved.
+Default is `false`.
+```
- Semicolon-separated list of regular expressions that the check ignores. Default is an
- empty list.
+```{option} AllowedIdentifiers
+Semicolon-separated list of regular expressions that the check ignores. Default is an
+empty list.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/return-const-ref-from-parameter.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/return-const-ref-from-parameter.md
index 663e2149c7ac9..11d4540f9d6d4 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/return-const-ref-from-parameter.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/return-const-ref-from-parameter.md
@@ -1,7 +1,7 @@
-.. title:: clang-tidy - bugprone-return-const-ref-from-parameter
+```{title} clang-tidy - bugprone-return-const-ref-from-parameter
+```
-bugprone-return-const-ref-from-parameter
-========================================
+# bugprone-return-const-ref-from-parameter
Detects return statements that return a constant reference parameter as
constant reference. This may cause use-after-free errors if the caller
@@ -12,40 +12,38 @@ destructed after the call. When the function returns such a parameter also
as constant reference, then the returned reference can be used after the
object it refers to has been destroyed.
-Example
--------
+## Example
-.. code-block:: c++
+```c++
+struct S {
+ int v;
+ S(int);
+ ~S();
+};
- struct S {
- int v;
- S(int);
- ~S();
- };
-
- const S &fn(const S &a) {
- return a;
- }
-
- const S& s = fn(S{1});
- s.v; // use after free
+const S &fn(const S &a) {
+ return a;
+}
+const S& s = fn(S{1});
+s.v; // use after free
+```
This issue can be resolved by declaring an overload of the problematic function
-where the ``const &`` parameter is instead declared as ``&&``. The developer has
+where the `const &` parameter is instead declared as `&&`. The developer has
to ensure that the implementation of that function does not produce a
use-after-free, the exact error that this check is warning against.
-Marking such an ``&&`` overload as ``deleted``, will silence the warning as
-well. In the case of different ``const &`` parameters being returned depending
+Marking such an `&&` overload as `deleted`, will silence the warning as
+well. In the case of different `const &` parameters being returned depending
on the control flow of the function, an overload where all problematic
-``const &`` parameters have been declared as ``&&`` will resolve the issue.
+`const &` parameters have been declared as `&&` will resolve the issue.
-This issue can also be resolved by adding ``[[clang::lifetimebound]]``. Clang
-enable ``-Wdangling`` warning by default which can detect mis-uses of the
-annotated function. See `lifetimebound attribute <https://clang.llvm.org/docs/AttributeReference.html#lifetimebound>`_
+This issue can also be resolved by adding `[[clang::lifetimebound]]`. Clang
+enable `-Wdangling` warning by default which can detect mis-uses of the
+annotated function. See [lifetimebound attribute](https://clang.llvm.org/docs/AttributeReference.html#lifetimebound)
for details.
-.. code-block:: c++
-
- const int &f(const int &a [[clang::lifetimebound]]) { return a; } // no warning
- const int &v = f(1); // warning: temporary bound to local reference 'v' will be destroyed at the end of the full-expression [-Wdangling]
+```c++
+const int &f(const int &a [[clang::lifetimebound]]) { return a; } // no warning
+const int &v = f(1); // warning: temporary bound to local reference 'v' will be destroyed at the end of the full-expression [-Wdangling]
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/shared-ptr-array-mismatch.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/shared-ptr-array-mismatch.md
index 003be010f359b..dd0420c6499ef 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/shared-ptr-array-mismatch.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/shared-ptr-array-mismatch.md
@@ -1,36 +1,35 @@
-.. title:: clang-tidy - bugprone-shared-ptr-array-mismatch
+```{title} clang-tidy - bugprone-shared-ptr-array-mismatch
+```
-bugprone-shared-ptr-array-mismatch
-==================================
+# bugprone-shared-ptr-array-mismatch
Finds initializations of C++ shared pointers to non-array type that are
initialized with an array.
-If a shared pointer ``std::shared_ptr<T>`` is initialized with a new-expression
-``new T[]`` the memory is not deallocated correctly. The pointer uses plain
-``delete`` in this case to deallocate the target memory. Instead a ``delete[]``
-call is needed. A ``std::shared_ptr<T[]>`` calls the correct delete operator.
+If a shared pointer `std::shared_ptr<T>` is initialized with a new-expression
+`new T[]` the memory is not deallocated correctly. The pointer uses plain
+`delete` in this case to deallocate the target memory. Instead a `delete[]`
+call is needed. A `std::shared_ptr<T[]>` calls the correct delete operator.
-The check offers replacement of ``shared_ptr<T>`` to ``shared_ptr<T[]>`` if it
+The check offers replacement of `shared_ptr<T>` to `shared_ptr<T[]>` if it
is used at a single variable declaration (one variable in one statement).
Example:
-.. code-block:: c++
+```c++
+std::shared_ptr<Foo> x(new Foo[10]); // -> std::shared_ptr<Foo[]> x(new Foo[10]);
+// ^ warning: shared pointer to non-array is initialized with array [bugprone-shared-ptr-array-mismatch]
+std::shared_ptr<Foo> x1(new Foo), x2(new Foo[10]); // no replacement
+// ^ warning: shared pointer to non-array is initialized with array [bugprone-shared-ptr-array-mismatch]
- std::shared_ptr<Foo> x(new Foo[10]); // -> std::shared_ptr<Foo[]> x(new Foo[10]);
- // ^ warning: shared pointer to non-array is initialized with array [bugprone-shared-ptr-array-mismatch]
- std::shared_ptr<Foo> x1(new Foo), x2(new Foo[10]); // no replacement
- // ^ warning: shared pointer to non-array is initialized with array [bugprone-shared-ptr-array-mismatch]
-
- std::shared_ptr<Foo> x3(new Foo[10], [](const Foo *ptr) { delete[] ptr; }); // no warning
+std::shared_ptr<Foo> x3(new Foo[10], [](const Foo *ptr) { delete[] ptr; }); // no warning
- struct S {
- std::shared_ptr<Foo> x(new Foo[10]); // no replacement in this case
- // ^ warning: shared pointer to non-array is initializ...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/214422
More information about the llvm-branch-commits
mailing list