[llvm-branch-commits] [clang-tools-extra] [clang-tidy][docs] Rewrite bugprone check docs to Markdown [1/4] (PR #214413)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Thu Aug 6 00:00:31 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-clang-tools-extra
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 98.21 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/214413.diff
20 Files Affected:
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md (+165-166)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/assert-side-effect.md (+27-28)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/assignment-in-selection-statement.md (+36-38)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/bitwise-pointer-cast.md (+30-30)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/branch-clone.md (+75-77)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/capturing-this-in-member-variable.md (+39-39)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/casting-through-void.md (+25-25)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/chained-comparison.md (+47-51)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/compare-pointer-to-member-virtual-function.md (+30-32)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/copy-constructor-init.md (+23-27)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/crtp-constructor-accessibility.md (+45-48)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/dangling-handle.md (+37-38)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/derived-method-shadowing-base-method.md (+18-18)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/easily-swappable-parameters.md (+209-211)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/empty-catch.md (+76-80)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/exception-copy-constructor-throws.md (+16-18)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/exception-escape.md (+75-76)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/fold-init-type.md (+25-25)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/forwarding-reference-overload.md (+33-35)
- (modified) clang-tools-extra/docs/clang-tidy/checks/bugprone/implicit-widening-of-multiplication-result.md (+40-42)
``````````diff
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md
index a5863ab32c41f..68f7a6eb7a260 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md
@@ -1,275 +1,274 @@
-.. title:: clang-tidy - bugprone-argument-comment
+```{title} clang-tidy - bugprone-argument-comment
+```
-bugprone-argument-comment
-=========================
+# bugprone-argument-comment
Checks that argument comments match parameter names and can optionally add
missing comments for literals, init-lists, and constructed temporaries.
-The check understands argument comments in the form ``/*parameter_name=*/``
+The check understands argument comments in the form `/*parameter_name=*/`
that are placed right before the argument.
-.. code-block:: c++
+```c++
+void f(bool foo);
- void f(bool foo);
+...
- ...
-
- f(/*bar=*/true);
- // warning: argument name 'bar' in comment does not match parameter name 'foo'
+f(/*bar=*/true);
+// warning: argument name 'bar' in comment does not match parameter name 'foo'
+```
The check tries to detect typos and suggest automated fixes for them. It can
also insert missing comments for configured argument kinds.
-Options
--------
-
-.. option:: StrictMode
-
- When `false`, the check will ignore leading and trailing
- underscores and case when comparing names -- otherwise they are taken into
- account. Default is `false`.
+## Options
-.. option:: IgnoreSingleArgument
+```{option} StrictMode
+When `false`, the check will ignore leading and trailing
+underscores and case when comparing names -- otherwise they are taken into
+account. Default is `false`.
+```
- When `true`, the check will ignore the single argument. Default is `false`.
+```{option} IgnoreSingleArgument
+When `true`, the check will ignore the single argument. Default is `false`.
+```
-.. option:: CommentAnonymousInitLists
-
- When `true`, the check will add argument comments in the format
- ``/*ParameterName=*/`` right before anonymous braced-init list arguments
- such as ``{}`` and ``{1, 2, 3}``. Default is `false`.
+```{option} CommentAnonymousInitLists
+When `true`, the check will add argument comments in the format
+`/*ParameterName=*/` right before anonymous braced-init list arguments
+such as `{}` and `{1, 2, 3}`. Default is `false`.
+```
Before:
-.. code-block:: c++
-
- void foo(const std::vector<int> &Dims);
+```c++
+void foo(const std::vector<int> &Dims);
- foo({});
+foo({});
+```
After:
-.. code-block:: c++
+```c++
+void foo(const std::vector<int> &Dims);
- void foo(const std::vector<int> &Dims);
+foo(/*Dims=*/{});
+```
- foo(/*Dims=*/{});
-
-.. option:: CommentBoolLiterals
-
- When `true`, the check will add argument comments in the format
- ``/*ParameterName=*/`` right before the boolean literal argument.
- Default is `false`.
+```{option} CommentBoolLiterals
+When `true`, the check will add argument comments in the format
+`/*ParameterName=*/` right before the boolean literal argument.
+Default is `false`.
+```
Before:
-.. code-block:: c++
+```c++
+void foo(bool TurnKey, bool PressButton);
- void foo(bool TurnKey, bool PressButton);
-
- foo(true, false);
+foo(true, false);
+```
After:
-.. code-block:: c++
-
- void foo(bool TurnKey, bool PressButton);
+```c++
+void foo(bool TurnKey, bool PressButton);
- foo(/*TurnKey=*/true, /*PressButton=*/false);
+foo(/*TurnKey=*/true, /*PressButton=*/false);
+```
-.. option:: CommentCharacterLiterals
-
- When `true`, the check will add argument comments in the format
- ``/*ParameterName=*/`` right before the character literal argument.
- Default is `false`.
+```{option} CommentCharacterLiterals
+When `true`, the check will add argument comments in the format
+`/*ParameterName=*/` right before the character literal argument.
+Default is `false`.
+```
Before:
-.. code-block:: c++
-
- void foo(char *Character);
+```c++
+void foo(char *Character);
- foo('A');
+foo('A');
+```
After:
-.. code-block:: c++
-
- void foo(char *Character);
-
- foo(/*Character=*/'A');
+```c++
+void foo(char *Character);
-.. option:: CommentFloatLiterals
+foo(/*Character=*/'A');
+```
- When `true`, the check will add argument comments in the format
- ``/*ParameterName=*/`` right before the float/double literal argument.
- Default is `false`.
+```{option} CommentFloatLiterals
+When `true`, the check will add argument comments in the format
+`/*ParameterName=*/` right before the float/double literal argument.
+Default is `false`.
+```
Before:
-.. code-block:: c++
+```c++
+void foo(float Pi);
- void foo(float Pi);
-
- foo(3.14159);
+foo(3.14159);
+```
After:
-.. code-block:: c++
-
- void foo(float Pi);
+```c++
+void foo(float Pi);
- foo(/*Pi=*/3.14159);
+foo(/*Pi=*/3.14159);
+```
-.. option:: CommentIntegerLiterals
-
- When `true`, the check will add argument comments in the format
- ``/*ParameterName=*/`` right before the integer literal argument.
- Default is `false`.
+```{option} CommentIntegerLiterals
+When `true`, the check will add argument comments in the format
+`/*ParameterName=*/` right before the integer literal argument.
+Default is `false`.
+```
Before:
-.. code-block:: c++
-
- void foo(int MeaningOfLife);
+```c++
+void foo(int MeaningOfLife);
- foo(42);
+foo(42);
+```
After:
-.. code-block:: c++
+```c++
+void foo(int MeaningOfLife);
- void foo(int MeaningOfLife);
+foo(/*MeaningOfLife=*/42);
+```
- foo(/*MeaningOfLife=*/42);
-
-.. option:: CommentNullPtrs
-
- When `true`, the check will add argument comments in the format
- ``/*ParameterName=*/`` right before the nullptr literal argument.
- Default is `false`.
+```{option} CommentNullPtrs
+When `true`, the check will add argument comments in the format
+`/*ParameterName=*/` right before the nullptr literal argument.
+Default is `false`.
+```
Before:
-.. code-block:: c++
+```c++
+void foo(A* Value);
- void foo(A* Value);
-
- foo(nullptr);
+foo(nullptr);
+```
After:
-.. code-block:: c++
-
- void foo(A* Value);
+```c++
+void foo(A* Value);
- foo(/*Value=*/nullptr);
+foo(/*Value=*/nullptr);
+```
-.. option:: CommentParenthesizedTemporaries
-
- When `true`, the check will add argument comments in the format
- ``/*ParameterName=*/`` right before explicit temporary constructions such as
- ``Type()`` and ``Type(1, 2, 3)``. Default is `false`.
+```{option} CommentParenthesizedTemporaries
+When `true`, the check will add argument comments in the format
+`/*ParameterName=*/` right before explicit temporary constructions such as
+`Type()` and `Type(1, 2, 3)`. Default is `false`.
+```
Before:
-.. code-block:: c++
-
- struct Dims {
- Dims();
- Dims(int, int, int);
- };
+```c++
+struct Dims {
+ Dims();
+ Dims(int, int, int);
+};
- void foo(const Dims &DimsValue);
+void foo(const Dims &DimsValue);
- foo(Dims());
- foo(Dims(1, 2, 3));
+foo(Dims());
+foo(Dims(1, 2, 3));
+```
After:
-.. code-block:: c++
-
- struct Dims {
- Dims();
- Dims(int, int, int);
- };
-
- void foo(const Dims &DimsValue);
+```c++
+struct Dims {
+ Dims();
+ Dims(int, int, int);
+};
- foo(/*DimsValue=*/Dims());
- foo(/*DimsValue=*/Dims(1, 2, 3));
+void foo(const Dims &DimsValue);
-.. option:: CommentStringLiterals
+foo(/*DimsValue=*/Dims());
+foo(/*DimsValue=*/Dims(1, 2, 3));
+```
- When `true`, the check will add argument comments in the format
- ``/*ParameterName=*/`` right before the string literal argument.
- Default is `false`.
+```{option} CommentStringLiterals
+When `true`, the check will add argument comments in the format
+`/*ParameterName=*/` right before the string literal argument.
+Default is `false`.
+```
Before:
-.. code-block:: c++
+```c++
+void foo(const char *String);
+void foo(const wchar_t *WideString);
- void foo(const char *String);
- void foo(const wchar_t *WideString);
-
- foo("Hello World");
- foo(L"Hello World");
+foo("Hello World");
+foo(L"Hello World");
+```
After:
-.. code-block:: c++
-
- void foo(const char *String);
- void foo(const wchar_t *WideString);
+```c++
+void foo(const char *String);
+void foo(const wchar_t *WideString);
- foo(/*String=*/"Hello World");
- foo(/*WideString=*/L"Hello World");
+foo(/*String=*/"Hello World");
+foo(/*WideString=*/L"Hello World");
+```
-.. option:: CommentTypedInitLists
-
- When `true`, the check will add argument comments in the format
- ``/*ParameterName=*/`` right before typed braced-init list arguments such
- as ``Type{}``. Default is `false`.
+```{option} CommentTypedInitLists
+When `true`, the check will add argument comments in the format
+`/*ParameterName=*/` right before typed braced-init list arguments such
+as `Type{}`. Default is `false`.
+```
Before:
-.. code-block:: c++
-
- void foo(const std::vector<int> &Dims);
+```c++
+void foo(const std::vector<int> &Dims);
- foo(std::vector<int>{});
+foo(std::vector<int>{});
+```
After:
-.. code-block:: c++
+```c++
+void foo(const std::vector<int> &Dims);
- void foo(const std::vector<int> &Dims);
+foo(/*Dims=*/std::vector<int>{});
+```
- foo(/*Dims=*/std::vector<int>{});
-
-.. option:: CommentUserDefinedLiterals
-
- When `true`, the check will add argument comments in the format
- ``/*ParameterName=*/`` right before the user defined literal argument.
- Default is `false`.
+```{option} CommentUserDefinedLiterals
+When `true`, the check will add argument comments in the format
+`/*ParameterName=*/` right before the user defined literal argument.
+Default is `false`.
+```
Before:
-.. code-block:: c++
+```c++
+void foo(double Distance);
- void foo(double Distance);
+double operator"" _km(long double);
- double operator"" _km(long double);
-
- foo(402.0_km);
+foo(402.0_km);
+```
After:
-.. code-block:: c++
-
- void foo(double Distance);
+```c++
+void foo(double Distance);
- double operator"" _km(long double);
+double operator"" _km(long double);
- foo(/*Distance=*/402.0_km);
+foo(/*Distance=*/402.0_km);
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/assert-side-effect.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/assert-side-effect.md
index 3ca712b958d04..b05596e065dc3 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/assert-side-effect.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/assert-side-effect.md
@@ -1,34 +1,33 @@
-.. title:: clang-tidy - bugprone-assert-side-effect
+```{title} clang-tidy - bugprone-assert-side-effect
+```
-bugprone-assert-side-effect
-===========================
+# bugprone-assert-side-effect
-Finds ``assert()`` with side effect.
+Finds `assert()` with side effect.
-The condition of ``assert()`` is evaluated only in debug builds so a
+The condition of `assert()` is evaluated only in debug builds so a
condition with side effect can cause different behavior in debug / release
builds.
-Options
--------
-
-.. option:: AssertMacros
-
- A comma-separated list of the names of assert macros to be checked.
- Default is `assert,NSAssert,NSCAssert`.
-
-.. option:: CheckFunctionCalls
-
- Whether to treat non-const member and non-member functions as they produce
- side effects. Disabled by default because it can increase the number of false
- positive warnings.
-
-.. option:: IgnoredFunctions
-
- A semicolon-separated list of the names of functions or methods to be
- considered as not having side-effects. Regular expressions are accepted,
- e.g. ``[Rr]ef(erence)?$`` matches every type with suffix ``Ref``, ``ref``,
- ``Reference`` and ``reference``. The default is empty. If a name in the list
- contains the sequence `::` it is matched against the qualified type name
- (i.e. ``namespace::Type``), otherwise it is matched against only
- the type name (i.e. ``Type``).
+## Options
+
+```{option} AssertMacros
+A comma-separated list of the names of assert macros to be checked.
+Default is `assert,NSAssert,NSCAssert`.
+```
+
+```{option} CheckFunctionCalls
+Whether to treat non-const member and non-member functions as they produce
+side effects. Disabled by default because it can increase the number of false
+positive warnings.
+```
+
+```{option} IgnoredFunctions
+A semicolon-separated list of the names of functions or methods to be
+considered as not having side-effects. Regular expressions are accepted,
+e.g. `[Rr]ef(erence)?$` matches every type with suffix `Ref`, `ref`,
+`Reference` and `reference`. The default is empty. If a name in the list
+contains the sequence `::` it is matched against the qualified type name
+(i.e. `namespace::Type`), otherwise it is matched against only
+the type name (i.e. `Type`).
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/assignment-in-selection-statement.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/assignment-in-selection-statement.md
index 0513ce3e3f771..27e7cac50f169 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/assignment-in-selection-statement.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/assignment-in-selection-statement.md
@@ -1,63 +1,61 @@
-.. title:: clang-tidy - bugprone-assignment-in-selection-statement
+```{title} clang-tidy - bugprone-assignment-in-selection-statement
+```
-bugprone-assignment-in-selection-statement
-==========================================
+# bugprone-assignment-in-selection-statement
Finds assignments within selection statements.
Such assignments may indicate programmer error because they may have been
-intended as equality tests. The selection statements are conditions of ``if``
-and loop (``for``, ``while``, ``do``) statements, condition of conditional
-operator (``?:``) and any operand of a binary logical operator (``&&``,
-``||``). The check finds assignments within these contexts if the single
+intended as equality tests. The selection statements are conditions of `if`
+and loop (`for`, `while`, `do`) statements, condition of conditional
+operator (`?:`) and any operand of a binary logical operator (`&&`,
+`||`). The check finds assignments within these contexts if the single
expression is an assignment or the assignment is contained (recursively) in
-last operand of a comma (``,``) operator or true and false expressions in a
+last operand of a comma (`,`) operator or true and false expressions in a
conditional operator. The warning is suppressed if the assignment is placed in
extra parentheses, but only if the assignment is the single expression of a
-condition (of ``if`` or a loop statement).
+condition (of `if` or a loop statement).
This check corresponds to the CERT rule
-`EXP45-C. Do not perform assignments in selection statements
-<https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/expressions-exp/exp45-c/>`_.
+[EXP45-C. Do not perform assignments in selection statements](https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/rules/expressions-exp/exp45-c/).
-Examples
-========
+# Examples
The check emits a warning in the following cases at the indicated locations:
-.. code-block:: c++
+```c++
+int x = 3;
- int x = 3;
+if (x = 4) // should it be `x == 4` instead of 'x = 4' ?
+ x = x + 1;
- if (x = 4) // should it be `x == 4` instead of 'x = 4' ?
- x = x + 1;
+while ((x <= 11) || (x = 22)) // assignment appears as operand of a logical operator
+ x += 2;
- while ((x <= 11) || (x = 22)) // assignment appears as operand of a logical operator
- x += 2;
+do {
+ x += 5;
+} while ((x > 10) ? (x = 11) : (x > 5)); // assignment in loop condition (from `x = 11`)
- do {
- x += 5;
- } while ((x > 10) ? (x = 11) : (x > 5)); // assignment in loop condition (from `x = 11`)
+for (int i = 0; i == 2, x = 5; ++i) // assignment in loop condition (from last operand of comma)
+ foo1(i, x);
- for (int i = 0; i == 2, x = 5; ++i) // assignment in loop condition (from last operand of comma)
- foo1(i, x);
+for (int i = 0; i == 2, (x = 5); ++i) // assignment is not a single expression, parentheses do not prevent the warning
+ foo1(i, x);
- for (int i = 0; i == 2, (x = 5); ++i) // assignment is not a single expression, parentheses do not prevent the warning
- foo1(i, x);
-
- int a = (x == 2) || (x = 3); // assignment appears in the operand a logical operator
+int a = (x == 2) || (x = 3); // assignment appears in the operand a logical operator
+```
The following cases do not produce a warning:
-.. code-block:: c++
-
- if ((x = 1)) { // a single assignment between parentheses
- x += 10;
+```c++
+if ((x = 1)) { // a single assignment between parentheses
+ x += 10;
- if ((x = 1) != 0) { // assignment appears in a complex expression and without a logical operator
- ++x;
+if ((x = 1) != 0) { // assignment appears in a complex expression and without a logical operator
+ ++x;
- if (foo(x = 9) && array[x = 8]) { // assignment appears in argument of function call or array index
- ++x;
+if (foo(x = 9) && array[x = 8]) { // assignment appears in argument of function call or array index
+ ++x;
- for (int i = 0; i = 2, x == 5; ++i) // assignment does not take part in the condition of the loop
- foo1(i, x);
+for (int i = 0; i = 2, x == 5; ++i) // assignment does not take part in the condition of the loop
+ foo1(i, x);
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/bitwise-pointer-cast.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/bitwise-pointer-cast.md
index 171e6e6157072..ae1478606492e 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/bitwise-pointer-cast.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/bitwise-pointer-cast.md
@@ -1,52 +1,52 @@
-.. title:: clang-tidy - bugprone-bitwise-pointer-cast
+```{title} clang-tidy - bugprone-bitwise-pointer-cast
+```
-bugprone-bitwise-pointer-cast
-=============================
+# bugprone-bitwise-pointer-cast
Warns about code that tries to cast between pointers by means of
-``std::bit_cast`` or ``memcpy``.
+`std::bit_cast` or `memcpy`.
-The motivation is that ``std::bit_cast`` is advertised as the safe alternative
-to type punning via ``reinterpret_cast`` in modern C++. However, one should not
-blindly replace ``reinterpret_cast`` with ``std::bit_cast``, as follows:
+The motivation is that `std::bit_cast` is advertised as the safe alternative
+to type punning via `reinterpret_cast` in modern C++. However, one should not
+blindly replace `reinterpret_cast` with `std::bit_cast`, as follows:
-.. code-block:: c++
+```c++
+int x{};
+-float y = *reinterpret_cast<float*>(&x);
++float y = *std::bit_cast<float*>(&x);
+```
- int x{};
- -float y = *reinterpret_cast<float*>(&x);
- +float y = *std::bit_cast<float*>(&x);
-
-The drop-in replacement behaves exactly the same as ``reinterpret_cast``, and
-Undefined Behavior is still invoked. ``std::bit_cast`` is copying the bytes of
+The drop-in replacement behaves exactly the same as `reinterpret_cast`, and
+Undefined Behavior is still invoked. `std::bit_cast` is copying the bytes of
the input pointer, not the pointee, into an output pointer of a different type,
which may violate the strict aliasing rules. However, simply looking at the
-code, it looks "safe", because it uses ``std::bit_cast`` which is advertised as
+code, it looks "safe", because it uses `std::bit_cast` which is advertised as
safe.
-The solution to safe type punning is to apply ``std::bit_cast`` on value types,
+The solution to safe type punning is to apply `std::bit_cast` on value types,
not on pointer types:
-.. code-block:: c++
-
- int x{};
- float y = std::bit_cast<float>(x);
+```c++
+int x{};
+float y = std::bit_cast<float>(x);
+```
This way, the bytes of the input object are copied into the output object,
which is much safer. Do note that Undefined Behavior can still occur, if there
-is no value of type ``To`` corresponding to the value representation produced.
+is no value of type `To` corresponding to the value representation produced.
Compilers may be able to optimize this copy and generate identical assembly to
-the original ``reinterpret_cast`` version.
+the original `reinterpret_cast` version.
-Code before C++20 may backport ``std::bit_cast`` by means of ``memcpy``, or
-simply call ``m...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/214413
More information about the llvm-branch-commits
mailing list