[llvm-branch-commits] [clang-tools-extra] [clang-tidy][docs] Rewrite readability check docs to Markdown [5/5] (PR #222033)
Zeyi Xu via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Sat Oct 3 06:13:31 PDT 2026
https://github.com/zeyi2 updated https://github.com/llvm/llvm-project/pull/222033
>From cb820c8ea99e26e1fb639721473baefdb3dbb784 Mon Sep 17 00:00:00 2001
From: Zeyi Xu <mitchell.xu2 at gmail.com>
Date: Tue, 8 Sep 2026 23:38:10 +0800
Subject: [PATCH 1/3] [clang-tidy][docs] Rewrite readability check docs to
Markdown [5/5]
---
.../static-accessed-through-instance.md | 48 ++--
.../checks/readability/string-compare.md | 113 ++++----
.../readability/suspicious-call-argument.md | 259 +++++++++---------
.../checks/readability/trailing-comma.md | 78 +++---
.../checks/readability/trivial-switch.md | 87 +++---
.../readability/uniqueptr-delete-release.md | 47 ++--
.../readability/uppercase-literal-suffix.md | 68 +++--
.../checks/readability/use-anyofallof.md | 86 +++---
.../use-concise-preprocessor-directives.md | 40 +--
9 files changed, 401 insertions(+), 425 deletions(-)
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/static-accessed-through-instance.md b/clang-tools-extra/docs/clang-tidy/checks/readability/static-accessed-through-instance.md
index ffb3738bf72c92a..06bb44c7aef4f5f 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/static-accessed-through-instance.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/static-accessed-through-instance.md
@@ -1,7 +1,7 @@
-.. title:: clang-tidy - readability-static-accessed-through-instance
+```{title} clang-tidy - readability-static-accessed-through-instance
+```
-readability-static-accessed-through-instance
-============================================
+# readability-static-accessed-through-instance
Checks for member expressions that access static members through instances, and
replaces them with uses of the appropriate qualified-id.
@@ -10,30 +10,30 @@ Example:
The following code:
-.. code-block:: c++
-
- struct C {
- static void foo();
- static int x;
- enum { E1 };
- enum E { E2 };
- };
-
- C *c1 = new C();
- c1->foo();
- c1->x;
- c1->E1;
- c1->E2;
+```c++
+struct C {
+ static void foo();
+ static int x;
+ enum { E1 };
+ enum E { E2 };
+};
+
+C *c1 = new C();
+c1->foo();
+c1->x;
+c1->E1;
+c1->E2;
+```
is changed to:
-.. code-block:: c++
-
- C *c1 = new C();
- C::foo();
- C::x;
- C::E1;
- C::E2;
+```c++
+C *c1 = new C();
+C::foo();
+C::x;
+C::E1;
+C::E2;
+```
The `--fix` commandline option provides default support for safe fixes, whereas
`--fix-notes` enables fixes that may replace expressions with side effects,
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md b/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md
index db9bec2ca850912..8aee86e99fcc2db 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md
@@ -1,87 +1,84 @@
-.. title:: clang-tidy - readability-string-compare
+```{title} clang-tidy - readability-string-compare
+```
-readability-string-compare
-==========================
+# readability-string-compare
Finds string comparisons using the compare method.
-A common mistake is to use the string's ``compare`` method instead of using the
+A common mistake is to use the string's `compare` method instead of using the
equality or inequality operators. The compare method is intended for sorting
functions and thus returns a negative number, a positive number or
zero depending on the lexicographical relationship between the strings
compared. If an equality or inequality check can suffice, that is recommended.
This is recommended to avoid the risk of incorrect interpretation of the return
value and to simplify the code. The string equality and inequality operators
-can also be faster than the ``compare`` method due to early termination.
+can also be faster than the `compare` method due to early termination.
-Example
--------
+## Example
-.. code-block:: c++
+```c++
+// The same rules apply to std::string_view.
+std::string str1{"a"};
+std::string str2{"b"};
- // The same rules apply to std::string_view.
- std::string str1{"a"};
- std::string str2{"b"};
+// use str1 != str2 instead.
+if (str1.compare(str2)) {
+}
- // use str1 != str2 instead.
- if (str1.compare(str2)) {
- }
+// use str1 == str2 instead.
+if (!str1.compare(str2)) {
+}
- // use str1 == str2 instead.
- if (!str1.compare(str2)) {
- }
+// use str1 == str2 instead.
+if (str1.compare(str2) == 0) {
+}
- // use str1 == str2 instead.
- if (str1.compare(str2) == 0) {
- }
+// use str1 != str2 instead.
+if (str1.compare(str2) != 0) {
+}
- // use str1 != str2 instead.
- if (str1.compare(str2) != 0) {
- }
+// use str1 == str2 instead.
+if (0 == str1.compare(str2)) {
+}
- // use str1 == str2 instead.
- if (0 == str1.compare(str2)) {
- }
+// use str1 != str2 instead.
+if (0 != str1.compare(str2)) {
+}
- // use str1 != str2 instead.
- if (0 != str1.compare(str2)) {
- }
-
- // Use str1 == "foo" instead.
- if (str1.compare("foo") == 0) {
- }
+// Use str1 == "foo" instead.
+if (str1.compare("foo") == 0) {
+}
+```
The above code examples show the list of if-statements that this check will
-give a warning for. All of them use ``compare`` to check equality or
+give a warning for. All of them use `compare` to check equality or
inequality of two strings instead of using the correct operators.
-Options
--------
-
-.. option:: StringLikeClasses
-
- A string containing semicolon-separated names of string-like classes.
- By default contains only ``::std::basic_string``
- and ``::std::basic_string_view``. If a class from this list has
- a ``compare`` method similar to that of ``std::string``, it will be checked
- in the same way.
+## Options
-Example
-^^^^^^^
+```{option} StringLikeClasses
+A string containing semicolon-separated names of string-like classes.
+If a class from this list has a `compare` method similar to that of
+`std::string`, it will be checked in the same way.
+Default is `::std::basic_string;::std::basic_string_view`.
+```
-.. code-block:: c++
+### Example
- struct CustomString {
- public:
- int compare (const CustomString& other) const;
- }
+```c++
+struct CustomString {
+public:
+ int compare (const CustomString& other) const;
+}
- CustomString str1;
- CustomString str2;
+CustomString str1;
+CustomString str2;
- // use str1 != str2 instead.
- if (str1.compare(str2)) {
- }
+// use str1 != str2 instead.
+if (str1.compare(str2)) {
+}
+```
-If `StringLikeClasses` contains ``CustomString``, the check will suggest
-replacing ``compare`` with equality operator.
+If {option}`StringLikeClasses` contains
+`CustomString`, the check will suggest
+replacing `compare` with equality operator.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/suspicious-call-argument.md b/clang-tools-extra/docs/clang-tidy/checks/readability/suspicious-call-argument.md
index 2b3a265d4af7f23..95fa9219c87018c 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/suspicious-call-argument.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/suspicious-call-argument.md
@@ -1,25 +1,24 @@
-.. title:: clang-tidy - readability-suspicious-call-argument
+```{title} clang-tidy - readability-suspicious-call-argument
+```
-readability-suspicious-call-argument
-====================================
+# readability-suspicious-call-argument
Finds function calls where the arguments passed are provided out of order,
based on the difference between the argument name and the parameter names
of the function.
-Given a function call ``f(foo, bar);`` and a function signature
-``void f(T tvar, U uvar)``, the arguments ``foo`` and ``bar`` are swapped if
-``foo`` (the argument name) is more similar to ``uvar`` (the other parameter)
-than ``tvar`` (the parameter it is currently passed to) **and** ``bar`` is
-more similar to ``tvar`` than ``uvar``.
+Given a function call `f(foo, bar);` and a function signature
+`void f(T tvar, U uvar)`, the arguments `foo` and `bar` are swapped if
+`foo` (the argument name) is more similar to `uvar` (the other parameter)
+than `tvar` (the parameter it is currently passed to) **and** `bar` is
+more similar to `tvar` than `uvar`.
Warnings might indicate either that the arguments are swapped, or that the
names' cross-similarity might hinder code comprehension.
-.. _heuristics:
+(heuristics)=
-Heuristics
-----------
+## Heuristics
The following heuristics are implemented in the check.
If **any** of the enabled heuristics deem the arguments to be provided out of
@@ -29,90 +28,83 @@ The heuristics themselves are implemented by considering pairs of strings, and
are symmetric, so in the following there is no distinction on which string is
the argument name and which string is the parameter name.
-Equality
-^^^^^^^^
+### Equality
The most trivial heuristic, which compares the two strings for case-insensitive
equality.
-.. _abbreviation_heuristic:
+(abbreviation_heuristic)=
-Abbreviation
-^^^^^^^^^^^^
+### Abbreviation
Common abbreviations can be specified which will deem the strings similar if
the abbreviated and the abbreviation stand together.
-For example, if ``src`` is registered as an abbreviation for ``source``, then
+For example, if `src` is registered as an abbreviation for `source`, then
the following code example will be warned about.
-.. code-block:: c++
+```c++
+void foo(int source, int x);
- void foo(int source, int x);
-
- foo(b, src);
+foo(b, src);
+```
The abbreviations to recognise can be configured with the
-:ref:`Abbreviations<opt_Abbreviations>` check option.
+{option}`Abbreviations` option.
This heuristic is case-insensitive.
-Prefix
-^^^^^^
+### Prefix
The *prefix* heuristic reports if one of the strings is a sufficiently long
-prefix of the other string, e.g. ``target`` to ``targetPtr``.
+prefix of the other string, e.g. `target` to `targetPtr`.
The similarity percentage is the length ratio of the prefix to the longer
-string, in the previous example, it would be `6 / 9 = 66.66...`\%.
+string, in the previous example, it would be `6 / 9 = 66.66...`%.
-This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
-The default bounds are: below `25`\% dissimilar and above `30`\% similar.
+This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+The default bounds are: below `25`% dissimilar and above `30`% similar.
This heuristic is case-insensitive.
-Suffix
-^^^^^^
+### Suffix
Analogous to the `Prefix` heuristic.
-In the case of ``oldValue`` and ``value`` compared, the similarity percentage
-is `8 / 5 = 62.5`\%.
+In the case of `oldValue` and `value` compared, the similarity percentage
+is `8 / 5 = 62.5`%.
-This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
-The default bounds are: below `25`\% dissimilar and above `30`\% similar.
+This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+The default bounds are: below `25`% dissimilar and above `30`% similar.
This heuristic is case-insensitive.
-Substring
-^^^^^^^^^
+### Substring
The substring heuristic combines the prefix and the suffix heuristic, and tries
to find the *longest common substring* in the two strings provided.
The similarity percentage is the ratio of the found longest common substring
against the *longer* of the two input strings.
-For example, given ``val`` and ``rvalue``, the similarity is `3 / 6 = 50`\%.
-If no characters are common in the two string, `0`\%.
+For example, given `val` and `rvalue`, the similarity is `3 / 6 = 50`%.
+If no characters are common in the two string, `0`%.
-This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
-The default bounds are: below `40`\% dissimilar and above `50`\% similar.
+This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+The default bounds are: below `40`% dissimilar and above `50`% similar.
This heuristic is case-insensitive.
-Levenshtein distance (as `Levenshtein`)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+### Levenshtein distance (as `Levenshtein`)
-The `Levenshtein distance <http://en.wikipedia.org/wiki/Levenshtein_distance>`_
+The [Levenshtein distance](http://en.wikipedia.org/wiki/Levenshtein_distance)
describes how many single-character changes (additions, changes, or removals)
must be applied to transform one string into another.
The Levenshtein distance is translated into a similarity percentage by dividing
it with the length of the *longer* string, and taking its complement with
-regards to `100`\%.
-For example, given ``something`` and ``anything``, the distance is `4` edits,
-and the similarity percentage is `100`\% `- 4 / 9 = 55.55...`\%.
+regards to `100`%.
+For example, given `something` and `anything`, the distance is `4` edits,
+and the similarity percentage is `100`% `- 4 / 9 = 55.55...`%.
-This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
-The default bounds are: below `50`\% dissimilar and above `66`\% similar.
+This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+The default bounds are: below `50`% dissimilar and above `66`% similar.
This heuristic is case-sensitive.
-Jaro--Winkler distance (as `JaroWinkler`)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+### Jaro--Winkler distance (as `JaroWinkler`)
-The `Jaro--Winkler distance <http://en.wikipedia.org/wiki/Jaro–Winkler_distance>`_
+The [Jaro--Winkler distance](http://en.wikipedia.org/wiki/Jaro–Winkler_distance)
is an edit distance like the Levenshtein distance.
It is calculated from the amount of common characters that are sufficiently
close to each other in position, and to-be-changed characters.
@@ -121,14 +113,13 @@ similarities more.
The similarity percentage is expressed as an average of the common and
non-common characters against the length of both strings.
-This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
-The default bounds are: below `75`\% dissimilar and above `85`\% similar.
+This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+The default bounds are: below `75`% dissimilar and above `85`% similar.
This heuristic is case-insensitive.
-Sørensen--Dice coefficient (as `Dice`)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+### Sørensen--Dice coefficient (as `Dice`)
-The `Sørensen--Dice coefficient <http://en.wikipedia.org/wiki/Sørensen–Dice_coefficient>`_
+The [Sørensen--Dice coefficient](http://en.wikipedia.org/wiki/Sørensen–Dice_coefficient)
was originally defined to measure the similarity of two sets.
Formally, the coefficient is calculated by dividing `2 * #(intersection)` with
`#(set1) + #(set2)`, where `#()` is the cardinality function of sets.
@@ -136,96 +127,92 @@ This metric is applied to strings by creating bigrams (substring sequences of
length 2) of the two strings and using the set of bigrams for the two strings
as the two sets.
-This heuristic can be configured with :ref:`bounds<opt_Bounds>`.
-The default bounds are: below `60`\% dissimilar and above `70`\% similar.
+This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+The default bounds are: below `60`% dissimilar and above `70`% similar.
This heuristic is case-insensitive.
-
-Options
--------
-
-.. option:: MinimumIdentifierNameLength
-
- Sets the minimum required length the argument and parameter names
- need to have. Names shorter than this length will be ignored.
- Defaults to `3`.
-
-.. _opt_Abbreviations:
-
-.. option:: Abbreviations
-
- For the **Abbreviation** heuristic
- (:ref:`see here<abbreviation_heuristic>`), this option configures the
- abbreviations in the `"abbreviation=abbreviated_value"` format.
- The option is a string, with each value joined by `";"`.
-
- By default, the following abbreviations are set:
-
- * `addr=address`
- * `arr=array`
- * `attr=attribute`
- * `buf=buffer`
- * `cl=client`
- * `cnt=count`
- * `col=column`
- * `cpy=copy`
- * `dest=destination`
- * `dist=distance`
- * `dst=distance`
- * `elem=element`
- * `hght=height`
- * `i=index`
- * `idx=index`
- * `len=length`
- * `ln=line`
- * `lst=list`
- * `nr=number`
- * `num=number`
- * `pos=position`
- * `ptr=pointer`
- * `ref=reference`
- * `src=source`
- * `srv=server`
- * `stmt=statement`
- * `str=string`
- * `val=value`
- * `var=variable`
- * `vec=vector`
- * `wdth=width`
+## Options
+
+```{option} MinimumIdentifierNameLength
+Sets the minimum required length the argument and parameter names
+need to have. Names shorter than this length will be ignored.
+Default is `3`.
+```
+
+(opt_Abbreviations)=
+
+```{option} Abbreviations
+For the **Abbreviation** heuristic
+({ref}`see here<abbreviation_heuristic>`), this option configures the
+abbreviations in the `"abbreviation=abbreviated_value"` format.
+The option is a string, with each value joined by `";"`.
+
+By default, the following abbreviations are set:
+
+- `addr=address`
+- `arr=array`
+- `attr=attribute`
+- `buf=buffer`
+- `cl=client`
+- `cnt=count`
+- `col=column`
+- `cpy=copy`
+- `dest=destination`
+- `dist=distance`
+- `dst=distance`
+- `elem=element`
+- `hght=height`
+- `i=index`
+- `idx=index`
+- `len=length`
+- `ln=line`
+- `lst=list`
+- `nr=number`
+- `num=number`
+- `pos=position`
+- `ptr=pointer`
+- `ref=reference`
+- `src=source`
+- `srv=server`
+- `stmt=statement`
+- `str=string`
+- `val=value`
+- `var=variable`
+- `vec=vector`
+- `wdth=width`
+```
The configuration options for each implemented heuristic (see above) is
constructed dynamically.
In the following, `<HeuristicName>` refers to one of the keys from the
heuristics implemented.
-.. option:: <HeuristicName>
-
- `True` or `False`, whether a particular heuristic, such as `Equality` or
- `Levenshtein` is enabled.
-
- Defaults to `True` for every heuristic.
-
-.. _opt_Bounds:
+```{option} <HeuristicName>
+`true` or `false`, whether a particular heuristic, such as `Equality` or
+`Levenshtein` is enabled.
-.. option:: <HeuristicName>DissimilarBelow, <HeuristicName>SimilarAbove
+Default is `true` for every heuristic.
+```
- A value between `0` and `100`, expressing a percentage.
- The bounds set what percentage of similarity the heuristic must deduce
- for the two identifiers to be considered similar or dissimilar by the
- check.
+(opt_Bounds)=
- Given arguments ``arg1`` and ``arg2`` passed to ``param1`` and ``param2``,
- respectively, the bounds check is performed in the following way:
- If the similarity of the currently passed argument order
- (``arg1`` to ``param1``) is **below** the `DissimilarBelow` threshold, and
- the similarity of the suggested swapped order (``arg1`` to ``param2``) is
- **above** the `SimilarAbove` threshold, the swap is reported.
+```{option} <HeuristicName>DissimilarBelow, <HeuristicName>SimilarAbove
+A value between `0` and `100`, expressing a percentage.
+The bounds set what percentage of similarity the heuristic must deduce
+for the two identifiers to be considered similar or dissimilar by the
+check.
- For the defaults of each heuristic, :ref:`see above<heuristics>`.
+Given arguments `arg1` and `arg2` passed to `param1` and `param2`,
+respectively, the bounds check is performed in the following way:
+If the similarity of the currently passed argument order
+(`arg1` to `param1`) is **below** the `DissimilarBelow` threshold, and
+the similarity of the suggested swapped order (`arg1` to `param2`) is
+**above** the `SimilarAbove` threshold, the swap is reported.
+For the defaults of each heuristic, {ref}`see above<heuristics>`.
+```
-Name synthesis
---------------
+## Name synthesis
When comparing the argument names and parameter names, the following logic is
used to gather the names for comparison:
@@ -234,9 +221,9 @@ Parameter names are the identifiers as written in the source code.
Argument names are:
- * If a variable is passed, the variable's name.
- * If a subsequent function call's return value is used as argument, the
- called function's name.
- * Otherwise, empty string.
+- If a variable is passed, the variable's name.
+- If a subsequent function call's return value is used as argument, the
+ called function's name.
+- Otherwise, empty string.
Empty argument or parameter names are ignored by the heuristics.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/trailing-comma.md b/clang-tools-extra/docs/clang-tidy/checks/readability/trailing-comma.md
index 83e05fb1bead695..3c6b5c352c44766 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/trailing-comma.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/trailing-comma.md
@@ -1,7 +1,7 @@
-.. title:: clang-tidy - readability-trailing-comma
+```{title} clang-tidy - readability-trailing-comma
+```
-readability-trailing-comma
-==========================
+# readability-trailing-comma
Checks for presence or absence of trailing commas in enum definitions and
initializer lists.
@@ -17,52 +17,48 @@ Trailing commas in multi-line constructs offer several benefits:
- Formatters may change code to a more desired style.
- Code generators avoid the need for special handling of the last element.
-.. code-block:: c++
+```c++
+// Without trailing commas - adding "Yellow" requires modifying the "Blue" line
+enum Color {
+ Red,
+ Green,
+ Blue
+};
- // Without trailing commas - adding "Yellow" requires modifying the "Blue" line
- enum Color {
- Red,
- Green,
- Blue
- };
+// With trailing commas - adding "Yellow" is a clean, single-line change
+enum Color {
+ Red,
+ Green,
+ Blue,
+};
+```
- // With trailing commas - adding "Yellow" is a clean, single-line change
- enum Color {
- Red,
- Green,
- Blue,
- };
-
-
-Limitations
------------
+## Limitations
The check currently doesn't analyze code inside macros.
+## Options
-Options
--------
-
-.. option:: SingleLineCommaPolicy
-
- Controls whether to add, remove, or ignore trailing commas in single-line
- enum definitions and initializer lists.
- Valid values are:
-
- - `Append`: Add trailing commas where missing.
- - `Remove`: Remove trailing commas where present.
- - `Ignore`: Do not check single-line constructs.
+```{option} SingleLineCommaPolicy
+Controls whether to add, remove, or ignore trailing commas in single-line
+enum definitions and initializer lists.
+Valid values are:
- Default is `Remove`.
+- `Append`: Add trailing commas where missing.
+- `Remove`: Remove trailing commas where present.
+- `Ignore`: Do not check single-line constructs.
-.. option:: MultiLineCommaPolicy
+Default is `Remove`.
+```
- Controls whether to add, remove, or ignore trailing commas in multi-line
- enum definitions and initializer lists.
- Valid values are:
+```{option} MultiLineCommaPolicy
+Controls whether to add, remove, or ignore trailing commas in multi-line
+enum definitions and initializer lists.
+Valid values are:
- - `Append`: Add trailing commas where missing.
- - `Remove`: Remove trailing commas where present.
- - `Ignore`: Do not check multi-line constructs.
+- `Append`: Add trailing commas where missing.
+- `Remove`: Remove trailing commas where present.
+- `Ignore`: Do not check multi-line constructs.
- Default is `Append`.
+Default is `Append`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/trivial-switch.md b/clang-tools-extra/docs/clang-tidy/checks/readability/trivial-switch.md
index dfed2576ffa81ee..3f0d49ad570aa10 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/trivial-switch.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/trivial-switch.md
@@ -1,44 +1,43 @@
-.. title:: clang-tidy - readability-trivial-switch
-
-readability-trivial-switch
-==========================
-
-Finds trivial ``switch`` statements that can be written more clearly.
-
-Every ``switch`` statement should have at least two ``case`` labels other than a ``default`` label.
-Otherwise, the ``switch`` can be better expressed with an ``if`` statement.
-``switch`` statements without any labels are diagnosed as well.
-
-.. code-block:: c++
-
- int i = 42;
-
- switch (i) {
- case 1:
- doSomething();
- break;
- default:
- doSomethingElse();
- break;
- }
-
- // The switch can be written more clearly as:
- if (i == 1) {
- doSomething();
- } else {
- doSomethingElse();
- }
-
-.. code-block:: c++
-
- // The switch without any labels will be diagnosed.
- int i = 42;
- switch (i) {}
-
-Options
--------
-
-.. option:: IgnoreMacros
-
- If set to `true`, the check will not give warnings inside macros. Default
- is `true`.
+```{title} clang-tidy - readability-trivial-switch
+```
+
+# readability-trivial-switch
+
+Finds trivial `switch` statements that can be written more clearly.
+
+Every `switch` statement should have at least two `case` labels other than a `default` label.
+Otherwise, the `switch` can be better expressed with an `if` statement.
+`switch` statements without any labels are diagnosed as well.
+
+```c++
+int i = 42;
+
+switch (i) {
+case 1:
+ doSomething();
+ break;
+default:
+ doSomethingElse();
+ break;
+}
+
+// The switch can be written more clearly as:
+if (i == 1) {
+ doSomething();
+} else {
+ doSomethingElse();
+}
+```
+
+```c++
+// The switch without any labels will be diagnosed.
+int i = 42;
+switch (i) {}
+```
+
+## Options
+
+```{option} IgnoreMacros
+When `true`, the check will not give warnings inside macros.
+Default is `true`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/uniqueptr-delete-release.md b/clang-tools-extra/docs/clang-tidy/checks/readability/uniqueptr-delete-release.md
index d5cee1587fb796f..4dee1273663ec09 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/uniqueptr-delete-release.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/uniqueptr-delete-release.md
@@ -1,35 +1,34 @@
-.. title:: clang-tidy - readability-uniqueptr-delete-release
+```{title} clang-tidy - readability-uniqueptr-delete-release
+```
-readability-uniqueptr-delete-release
-====================================
+# readability-uniqueptr-delete-release
-Replace ``delete <unique_ptr>.release()`` with ``<unique_ptr> = nullptr``.
+Replace `delete <unique_ptr>.release()` with `<unique_ptr> = nullptr`.
The latter is shorter, simpler and does not require use of raw pointer APIs.
-.. code-block:: c++
+```c++
+std::unique_ptr<int> P;
+delete P.release();
- std::unique_ptr<int> P;
- delete P.release();
+// becomes
- // becomes
+std::unique_ptr<int> P;
+P = nullptr;
+```
- std::unique_ptr<int> P;
- P = nullptr;
+## Options
-Options
--------
+````{option} PreferResetCall
+When `true`, refactor by calling the reset member function instead of
+assigning to `nullptr`. Default is `false`.
-.. option:: PreferResetCall
+```c++
+std::unique_ptr<int> P;
+delete P.release();
- If `true`, refactor by calling the reset member function instead of
- assigning to ``nullptr``. Default value is `false`.
+// becomes
- .. code-block:: c++
-
- std::unique_ptr<int> P;
- delete P.release();
-
- // becomes
-
- std::unique_ptr<int> P;
- P.reset();
+std::unique_ptr<int> P;
+P.reset();
+```
+````
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/uppercase-literal-suffix.md b/clang-tools-extra/docs/clang-tidy/checks/readability/uppercase-literal-suffix.md
index ea254bd4c234e6d..e30ef3c86e8a07d 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/uppercase-literal-suffix.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/uppercase-literal-suffix.md
@@ -1,11 +1,11 @@
-.. title:: clang-tidy - readability-uppercase-literal-suffix
+```{title} clang-tidy - readability-uppercase-literal-suffix
+```
-readability-uppercase-literal-suffix
-====================================
+# readability-uppercase-literal-suffix
`cert-dcl16-c` redirects here as an alias for this check.
-By default, only the suffixes that begin with ``l`` (``l``, ``ll``, ``lu``,
-``llu``, but not ``u``, ``ul``, ``ull``) are diagnosed by that alias.
+By default, only the suffixes that begin with `l` (`l`, `ll`, `lu`,
+`llu`, but not `u`, `ul`, `ull`) are diagnosed by that alias.
Detects when the integral literal or floating point (decimal or hexadecimal)
literal has a non-uppercase suffix and provides a fix-it hint with the
@@ -13,42 +13,40 @@ uppercase suffix.
All valid combinations of suffixes are supported.
-.. code:: c
+```c
+auto x = 1; // OK, no suffix.
- auto x = 1; // OK, no suffix.
+auto x = 1u; // warning: integer literal suffix 'u' is not upper-case
- auto x = 1u; // warning: integer literal suffix 'u' is not upper-case
+auto x = 1U; // OK, suffix is uppercase.
- auto x = 1U; // OK, suffix is uppercase.
+...
+```
- ...
+## Options
-Options
--------
+```{option} NewSuffixes
+Optionally, a list of the destination suffixes can be provided. When the
+suffix is found, a case-insensitive lookup in that list is made, and if a
+replacement is found that is different from the current suffix, then the
+diagnostic is issued. This allows for fine-grained control of what suffixes to
+consider and what their replacements should be.
+```
-.. option:: NewSuffixes
-
- Optionally, a list of the destination suffixes can be provided. When the
- suffix is found, a case-insensitive lookup in that list is made, and if a
- replacement is found that is different from the current suffix, then the
- diagnostic is issued. This allows for fine-grained control of what suffixes to
- consider and what their replacements should be.
-
-Example
-^^^^^^^
+### Example
Given a list `L;uL`:
-* ``l`` -> ``L``
-* ``L`` will be kept as is.
-* ``ul`` -> ``uL``
-* ``Ul`` -> ``uL``
-* ``UL`` -> ``uL``
-* ``uL`` will be kept as is.
-* ``ull`` will be kept as is, since it is not in the list
-* and so on.
-
-.. option:: IgnoreMacros
-
- If this option is set to `true` (default is `true`), the check will not warn
- about literal suffixes inside macros.
+- `l` -> `L`
+- `L` will be kept as is.
+- `ul` -> `uL`
+- `Ul` -> `uL`
+- `UL` -> `uL`
+- `uL` will be kept as is.
+- `ull` will be kept as is, since it is not in the list
+- and so on.
+
+```{option} IgnoreMacros
+When `true`, the check will not warn about literal suffixes inside macros.
+Default is `true`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/use-anyofallof.md b/clang-tools-extra/docs/clang-tidy/checks/readability/use-anyofallof.md
index b3d5e678aea0272..9e1c52fdd054269 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/use-anyofallof.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/use-anyofallof.md
@@ -1,64 +1,64 @@
-.. title:: clang-tidy - readability-use-anyofallof
+```{title} clang-tidy - readability-use-anyofallof
+```
-readability-use-anyofallof
-==========================
+# readability-use-anyofallof
Finds range-based for loops that can be replaced by a call to
-``std::any_of`` or ``std::all_of``. In C++20 mode, suggests
-``std::ranges::any_of`` or ``std::ranges::all_of``.
+`std::any_of` or `std::all_of`. In C++20 mode, suggests
+`std::ranges::any_of` or `std::ranges::all_of`.
Example:
-.. code-block:: c++
-
- bool all_even(const std::vector<int> &V) {
- for (int I : V) {
- if (I % 2)
- return false;
- }
- return true;
+```c++
+bool all_even(const std::vector<int> &V) {
+ for (int I : V) {
+ if (I % 2)
+ return false;
}
- // Replace loop by
- // return std::ranges::all_of(V, [](int I) { return I % 2 == 0; }); (C++20)
- // return std::all_of(V.begin(), V.end(), [](int I) { return I % 2 == 0; }); (pre-C++20)
+ return true;
+}
+// Replace loop by
+// return std::ranges::all_of(V, [](int I) { return I % 2 == 0; }); (C++20)
+// return std::all_of(V.begin(), V.end(), [](int I) { return I % 2 == 0; }); (pre-C++20)
+```
When using a raw initializer list or a temporary range (pre-C++20), it's
recommended to materialize it in a local variable first to avoid potential
lifetime issues. In C++20, temporary ranges can be used directly with
-``std::ranges`` algorithms as they handle the lifetime of a temporary range
+`std::ranges` algorithms as they handle the lifetime of a temporary range
correctly.
Example with raw initializer list:
-.. code-block:: c++
-
- bool contains_zero(int a, int b, int c) {
- for (int i : {a, b, c}) {
- if (i == 0)
- return true;
- }
- return false;
+```c++
+bool contains_zero(int a, int b, int c) {
+ for (int i : {a, b, c}) {
+ if (i == 0)
+ return true;
}
- // Replace loop by
- // auto range = {a, b, c};
- // return std::ranges::any_of(range, [](int i) { return i == 0; }); (C++20)
- // return std::any_of(range.begin(), range.end(), [](int i) { return i == 0; }); (pre-C++20)
+ return false;
+}
+// Replace loop by
+// auto range = {a, b, c};
+// return std::ranges::any_of(range, [](int i) { return i == 0; }); (C++20)
+// return std::any_of(range.begin(), range.end(), [](int i) { return i == 0; }); (pre-C++20)
+```
Example with temporary range:
-.. code-block:: c++
-
- extern std::vector<int> get_values();
+```c++
+extern std::vector<int> get_values();
- bool has_even() {
- for (int i : get_values()) {
- if (i % 2 == 0)
- return true;
- }
- return false;
+bool has_even() {
+ for (int i : get_values()) {
+ if (i % 2 == 0)
+ return true;
}
- // Replace loop by
- // return std::ranges::any_of(get_values(), [](int i) { return i % 2 == 0; }); (C++20)
- //
- // auto values = get_values();
- // return std::any_of(values.begin(), values.end(), [](int i) { return i % 2 == 0; }); (pre-C++20)
+ return false;
+}
+// Replace loop by
+// return std::ranges::any_of(get_values(), [](int i) { return i % 2 == 0; }); (C++20)
+//
+// auto values = get_values();
+// return std::any_of(values.begin(), values.end(), [](int i) { return i % 2 == 0; }); (pre-C++20)
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/use-concise-preprocessor-directives.md b/clang-tools-extra/docs/clang-tidy/checks/readability/use-concise-preprocessor-directives.md
index 30ec7e6b899365e..300ace991aaf2f5 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/use-concise-preprocessor-directives.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/use-concise-preprocessor-directives.md
@@ -1,30 +1,30 @@
-.. title:: clang-tidy - readability-use-concise-preprocessor-directives
+```{title} clang-tidy - readability-use-concise-preprocessor-directives
+```
-readability-use-concise-preprocessor-directives
-===============================================
+# readability-use-concise-preprocessor-directives
-Finds uses of ``#if`` that can be simplified to ``#ifdef`` or ``#ifndef`` and,
-since C23 and C++23, uses of ``#elif`` that can be simplified to ``#elifdef``
-or ``#elifndef``:
+Finds uses of `#if` that can be simplified to `#ifdef` or `#ifndef` and,
+since C23 and C++23, uses of `#elif` that can be simplified to `#elifdef`
+or `#elifndef`:
-.. code-block:: c++
+```c++
+#if defined(MEOW)
+#if !defined(MEOW)
- #if defined(MEOW)
- #if !defined(MEOW)
+// becomes
- // becomes
-
- #ifdef MEOW
- #ifndef MEOW
+#ifdef MEOW
+#ifndef MEOW
+```
Since C23 and C++23:
-.. code-block:: c++
-
- #elif defined(MEOW)
- #elif !defined(MEOW)
+```c++
+#elif defined(MEOW)
+#elif !defined(MEOW)
- // becomes
+// becomes
- #elifdef MEOW
- #elifndef MEOW
+#elifdef MEOW
+#elifndef MEOW
+```
>From e513e2bcd20bd5c13dc4fb3d6ea1576cde985e50 Mon Sep 17 00:00:00 2001
From: Zeyi Xu <mitchell.xu2 at gmail.com>
Date: Sat, 3 Oct 2026 01:32:57 +0800
Subject: [PATCH 2/3] [clang-tidy][docs] Address readability Markdown review
feedback [5/5]
---
.../checks/readability/string-compare.md | 2 +-
.../readability/suspicious-call-argument.md | 31 ++++++++++---------
.../readability/uppercase-literal-suffix.md | 2 +-
3 files changed, 19 insertions(+), 16 deletions(-)
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md b/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md
index 8aee86e99fcc2db..9ab1af52d0b6bae 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md
@@ -69,7 +69,7 @@ Default is `::std::basic_string;::std::basic_string_view`.
struct CustomString {
public:
int compare (const CustomString& other) const;
-}
+};
CustomString str1;
CustomString str2;
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/suspicious-call-argument.md b/clang-tools-extra/docs/clang-tidy/checks/readability/suspicious-call-argument.md
index 95fa9219c87018c..2d2d5fb0827bbce 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/suspicious-call-argument.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/suspicious-call-argument.md
@@ -49,7 +49,7 @@ foo(b, src);
```
The abbreviations to recognise can be configured with the
-{option}`Abbreviations` option.
+{option}`Abbreviations`.
This heuristic is case-insensitive.
### Prefix
@@ -59,7 +59,8 @@ prefix of the other string, e.g. `target` to `targetPtr`.
The similarity percentage is the length ratio of the prefix to the longer
string, in the previous example, it would be `6 / 9 = 66.66...`%.
-This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+This heuristic can be configured with {option}`<HeuristicName>DissimilarBelow` and
+{option}`<HeuristicName>SimilarAbove`.
The default bounds are: below `25`% dissimilar and above `30`% similar.
This heuristic is case-insensitive.
@@ -67,9 +68,10 @@ This heuristic is case-insensitive.
Analogous to the `Prefix` heuristic.
In the case of `oldValue` and `value` compared, the similarity percentage
-is `8 / 5 = 62.5`%.
+is `5 / 8 = 62.5`%.
-This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+This heuristic can be configured with {option}`<HeuristicName>DissimilarBelow` and
+{option}`<HeuristicName>SimilarAbove`.
The default bounds are: below `25`% dissimilar and above `30`% similar.
This heuristic is case-insensitive.
@@ -82,7 +84,8 @@ against the *longer* of the two input strings.
For example, given `val` and `rvalue`, the similarity is `3 / 6 = 50`%.
If no characters are common in the two string, `0`%.
-This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+This heuristic can be configured with {option}`<HeuristicName>DissimilarBelow` and
+{option}`<HeuristicName>SimilarAbove`.
The default bounds are: below `40`% dissimilar and above `50`% similar.
This heuristic is case-insensitive.
@@ -98,7 +101,8 @@ regards to `100`%.
For example, given `something` and `anything`, the distance is `4` edits,
and the similarity percentage is `100`% `- 4 / 9 = 55.55...`%.
-This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+This heuristic can be configured with {option}`<HeuristicName>DissimilarBelow` and
+{option}`<HeuristicName>SimilarAbove`.
The default bounds are: below `50`% dissimilar and above `66`% similar.
This heuristic is case-sensitive.
@@ -113,7 +117,8 @@ similarities more.
The similarity percentage is expressed as an average of the common and
non-common characters against the length of both strings.
-This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+This heuristic can be configured with {option}`<HeuristicName>DissimilarBelow` and
+{option}`<HeuristicName>SimilarAbove`.
The default bounds are: below `75`% dissimilar and above `85`% similar.
This heuristic is case-insensitive.
@@ -127,7 +132,8 @@ This metric is applied to strings by creating bigrams (substring sequences of
length 2) of the two strings and using the set of bigrams for the two strings
as the two sets.
-This heuristic can be configured with {ref}`bounds<opt_Bounds>`.
+This heuristic can be configured with {option}`<HeuristicName>DissimilarBelow` and
+{option}`<HeuristicName>SimilarAbove`.
The default bounds are: below `60`% dissimilar and above `70`% similar.
This heuristic is case-insensitive.
@@ -139,8 +145,6 @@ need to have. Names shorter than this length will be ignored.
Default is `3`.
```
-(opt_Abbreviations)=
-
```{option} Abbreviations
For the **Abbreviation** heuristic
({ref}`see here<abbreviation_heuristic>`), this option configures the
@@ -194,8 +198,6 @@ heuristics implemented.
Default is `true` for every heuristic.
```
-(opt_Bounds)=
-
```{option} <HeuristicName>DissimilarBelow, <HeuristicName>SimilarAbove
A value between `0` and `100`, expressing a percentage.
The bounds set what percentage of similarity the heuristic must deduce
@@ -205,9 +207,10 @@ check.
Given arguments `arg1` and `arg2` passed to `param1` and `param2`,
respectively, the bounds check is performed in the following way:
If the similarity of the currently passed argument order
-(`arg1` to `param1`) is **below** the `DissimilarBelow` threshold, and
+(`arg1` to `param1`) is **below** the
+{option}`<HeuristicName>DissimilarBelow` threshold, and
the similarity of the suggested swapped order (`arg1` to `param2`) is
-**above** the `SimilarAbove` threshold, the swap is reported.
+**above** the {option}`<HeuristicName>SimilarAbove` threshold, the swap is reported.
For the defaults of each heuristic, {ref}`see above<heuristics>`.
```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/uppercase-literal-suffix.md b/clang-tools-extra/docs/clang-tidy/checks/readability/uppercase-literal-suffix.md
index e30ef3c86e8a07d..0795b79ecb1228b 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/uppercase-literal-suffix.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/uppercase-literal-suffix.md
@@ -30,7 +30,7 @@ Optionally, a list of the destination suffixes can be provided. When the
suffix is found, a case-insensitive lookup in that list is made, and if a
replacement is found that is different from the current suffix, then the
diagnostic is issued. This allows for fine-grained control of what suffixes to
-consider and what their replacements should be.
+consider and what their replacements should be. Default is empty string.
```
### Example
>From fd75db8d01a6ce52fa915fd7d60efc7381804312 Mon Sep 17 00:00:00 2001
From: Zeyi Xu <zeyi2 at nekoarch.cc>
Date: Sat, 3 Oct 2026 21:13:12 +0800
Subject: [PATCH 3/3] Update
clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md
Co-authored-by: EugeneZelenko <eugene.zelenko at gmail.com>
---
.../docs/clang-tidy/checks/readability/string-compare.md | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md b/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md
index 9ab1af52d0b6bae..2b48dbcf2a66d36 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/string-compare.md
@@ -79,6 +79,5 @@ if (str1.compare(str2)) {
}
```
-If {option}`StringLikeClasses` contains
-`CustomString`, the check will suggest
+If {option}`StringLikeClasses` contains `CustomString`, the check will suggest
replacing `compare` with equality operator.
More information about the llvm-branch-commits
mailing list