[llvm-branch-commits] [clang-tools-extra] [clang-tidy][docs] Rewrite readability check docs to Markdown [2/5] (PR #221529)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Sat Sep 5 23:25:38 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>
Tracking issue: #<!-- -->201242
See the [migration guide] for more information.
[migration guide]:
https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines
This is the second part of rewriting check documentations in readability module from reST to MyST Markdown.
AI Usage: This was prepared with rnk's fork of rst2myst and GPT5.6-assisted cleanup.
I manually verified that the documentation renders as expected.
Preview site:
https://broken.life/llvm-staging/readability-markdown-port/index.html
---
Patch is 222.76 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/221529.diff
10 Files Affected:
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/function-cognitive-complexity.md (+110-108)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/function-size.md (+48-49)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/identifier-length.md (+138-137)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/identifier-naming.md (+2490-2513)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/implicit-bool-conversion.md (+90-100)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/inconsistent-declaration-parameter-name.md (+31-33)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/inconsistent-ifelse-braces.md (+31-31)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/isolate-declaration.md (+68-71)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/magic-numbers.md (+95-97)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/make-member-function-const.md (+42-42)
``````````diff
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/function-cognitive-complexity.md b/clang-tools-extra/docs/clang-tidy/checks/readability/function-cognitive-complexity.md
index 430006e68ceb4..9623ce977eabc 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/function-cognitive-complexity.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/function-cognitive-complexity.md
@@ -1,166 +1,168 @@
-.. title:: clang-tidy - readability-function-cognitive-complexity
+```{title} clang-tidy - readability-function-cognitive-complexity
+```
-readability-function-cognitive-complexity
-=========================================
+# readability-function-cognitive-complexity
Checks function Cognitive Complexity metric.
-The metric is implemented as per the `COGNITIVE COMPLEXITY by SonarSource
-<https://www.sonarsource.com/docs/CognitiveComplexity.pdf>`_ specification
+The metric is implemented as per the [COGNITIVE COMPLEXITY by SonarSource](https://www.sonarsource.com/docs/CognitiveComplexity.pdf) specification
version 1.2 (19 April 2017).
-Options
--------
+## Options
-.. option:: Threshold
+```{option} Threshold
+Flag functions with Cognitive Complexity exceeding this number.
+Default is `25`.
+```
- Flag functions with Cognitive Complexity exceeding this number.
- The default is `25`.
+```{option} DescribeBasicIncrements
+When `true`, for each function exceeding the complexity threshold
+the check will issue additional diagnostics on every piece of code (loop,
+`if` statement, etc.) which contributes to that complexity. See also the
+examples below. Default is `true`.
+```
-.. option:: DescribeBasicIncrements
+```{option} IgnoreMacros
+When `true`, the check will ignore code inside macros. Note that
+any macro arguments are ignored, even if they should count to the complexity.
+As this might change in the future, this option isn't guaranteed to be
+forward-compatible. Default is `false`.
+```
- If set to `true`, then for each function exceeding the complexity threshold
- the check will issue additional diagnostics on every piece of code (loop,
- `if` statement, etc.) which contributes to that complexity. See also the
- examples below. Default is `true`.
-
-.. option:: IgnoreMacros
-
- If set to `true`, the check will ignore code inside macros. Note, that also
- any macro arguments are ignored, even if they should count to the complexity.
- As this might change in the future, this option isn't guaranteed to be
- forward-compatible. Default is `false`.
-
-Building blocks
----------------
+## Building blocks
There are three basic building blocks of a Cognitive Complexity metric:
-Increment
-^^^^^^^^^
+### Increment
The following structures increase the function's Cognitive Complexity metric
(by `1`):
-* Conditional operators:
+- Conditional operators:
+
+ - `if()`
+ - `else if()`
+ - `else`
+ - `cond ? true : false`
+
+- `switch()`
+
+- Loops:
- - ``if()``
- - ``else if()``
- - ``else``
- - ``cond ? true : false``
+ - `for()`
+ - C++11 range-based `for()`
+ - `while()`
+ - `do while()`
-* ``switch()``
-* Loops:
+- `catch ()`
- - ``for()``
- - C++11 range-based ``for()``
- - ``while()``
- - ``do while()``
+- `goto LABEL`, `goto *(&&LABEL))`,
-* ``catch ()``
-* ``goto LABEL``, ``goto *(&&LABEL))``,
-* sequences of binary logical operators:
+- sequences of binary logical operators:
- - ``boolean1 || boolean2``
- - ``boolean1 && boolean2``
+ - `boolean1 || boolean2`
+ - `boolean1 && boolean2`
-Nesting level
-^^^^^^^^^^^^^
+### Nesting level
While by itself the nesting level does not change the function's Cognitive
Complexity metric, it is tracked, and is used by the next, third building
block. The following structures increase the nesting level (by `1`):
-* Conditional operators:
+- Conditional operators:
- - ``if()``
- - ``else if()``
- - ``else``
- - ``cond ? true : false``
+ - `if()`
+ - `else if()`
+ - `else`
+ - `cond ? true : false`
-* ``switch()``
-* Loops:
+- `switch()`
- - ``for()``
- - C++11 range-based ``for()``
- - ``while()``
- - ``do while()``
+- Loops:
-* ``catch ()``
-* Nested functions:
+ - `for()`
+ - C++11 range-based `for()`
+ - `while()`
+ - `do while()`
- - C++11 Lambda
- - Nested ``class``
- - Nested ``struct``
-* GNU statement expression
-* Apple Block Declaration
+- `catch ()`
-Nesting increment
-^^^^^^^^^^^^^^^^^
+- Nested functions:
-This is where the previous basic building block, `Nesting level`_, matters.
-The following structures increase the function's Cognitive Complexity metric by
-the current `Nesting level`_:
+ - C++11 Lambda
+ - Nested `class`
+ - Nested `struct`
-* Conditional operators:
+- GNU statement expression
- - ``if()``
- - ``cond ? true : false``
+- Apple Block Declaration
-* ``switch()``
-* Loops:
+### Nesting increment
- - ``for()``
- - C++11 range-based ``for()``
- - ``while()``
- - ``do while()``
+This is where the previous basic building block,
+[Nesting level](#nesting-level), matters.
+The following structures increase the function's Cognitive Complexity metric by
+the current [Nesting level](#nesting-level):
-* ``catch ()``
+- Conditional operators:
-Examples
---------
+ - `if()`
+ - `cond ? true : false`
-The simplest case. This function has Cognitive Complexity of `0`.
+- `switch()`
-.. code-block:: c++
+- Loops:
- void function0() {}
+ - `for()`
+ - C++11 range-based `for()`
+ - `while()`
+ - `do while()`
-Slightly better example. This function has Cognitive Complexity of `1`.
+- `catch ()`
-.. code-block:: c++
+## Examples
- int function1(bool var) {
- if(var) // +1, nesting level +1
- return 42;
- return 0;
- }
+The simplest case. This function has Cognitive Complexity of `0`.
-Full example. This function has Cognitive Complexity of `3`.
+```c++
+void function0() {}
+```
+
+Slightly better example. This function has Cognitive Complexity of `1`.
-.. code-block:: c++
+```c++
+int function1(bool var) {
+ if(var) // +1, nesting level +1
+ return 42;
+ return 0;
+}
+```
- int function3(bool var1, bool var2) {
- if(var1) { // +1, nesting level +1
- if(var2) // +2 (1 + current nesting level of 1), nesting level +1
- return 42;
- }
+Full example. This function has Cognitive Complexity of `3`.
- return 0;
+```c++
+int function3(bool var1, bool var2) {
+ if(var1) { // +1, nesting level +1
+ if(var2) // +2 (1 + current nesting level of 1), nesting level +1
+ return 42;
}
-In the last example, the check will flag `function3` if the option Threshold is
-set to `2` or smaller. If the option DescribeBasicIncrements is set to `true`,
+ return 0;
+}
+```
+
+In the last example, the check will flag `function3` if the
+{option}`Threshold` option is set to `2` or smaller. If the
+{option}`DescribeBasicIncrements` option is set to `true`,
it will additionally flag the two `if` statements with the amounts by which they
increase to the complexity of the function and the current nesting level.
-
-Limitations
------------
+## Limitations
The metric is implemented with two notable exceptions:
- * `preprocessor conditionals` (``#ifdef``, ``#if``, ``#elif``, ``#else``,
- ``#endif``) are not accounted for.
- * `each method in a recursion cycle` is not accounted for. It can't be fully
- implemented, because cross-translational-unit analysis would be needed,
- which is currently not possible in clang-tidy.
+
+- `preprocessor conditionals` (`#ifdef`, `#if`, `#elif`, `#else`,
+ `#endif`) are not accounted for.
+- `each method in a recursion cycle` is not accounted for. It can't be fully
+ implemented, because cross-translational-unit analysis would be needed,
+ which is currently not possible in clang-tidy.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/function-size.md b/clang-tools-extra/docs/clang-tidy/checks/readability/function-size.md
index a87862f77c366..37d96bd14e673 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/function-size.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/function-size.md
@@ -1,55 +1,54 @@
-.. title:: clang-tidy - readability-function-size
+```{title} clang-tidy - readability-function-size
+```
-readability-function-size
-=========================
+# readability-function-size
`google-readability-function-size` redirects here as an alias for this check.
Checks for large functions based on various metrics.
-Options
--------
-
-.. option:: LineThreshold
-
- Flag functions exceeding this number of lines. The default is `none` (ignore
- the number of lines).
-
-.. option:: StatementThreshold
-
- Flag functions exceeding this number of statements. This may differ
- significantly from the number of lines for macro-heavy code. The default is
- `800`.
-
-.. option:: BranchThreshold
-
- Flag functions exceeding this number of control statements. The default is
- `none` (ignore the number of branches).
-
-.. option:: ParameterThreshold
-
- Flag functions that exceed a specified number of parameters. The default
- is `none` (ignore the number of parameters).
-
-.. option:: NestingThreshold
-
- Flag compound statements which create next nesting level after
- `NestingThreshold`. This may differ significantly from the expected value
- for macro-heavy code. The default is `none` (ignore the nesting level).
-
-.. option:: VariableThreshold
-
- Flag functions exceeding this number of variables declared in the body.
- The default is `none` (ignore the number of variables).
- Please note that function parameters and variables declared in lambdas,
- GNU Statement Expressions, and nested class inline functions are not counted.
-
-.. option:: CountMemberInitAsStmt
-
- When `true`, count class member initializers in constructors as statements.
- Default is `true`.
-
-.. option:: IgnoreMacros
-
- If set to `true`, the check will not count statements, branches, nesting
- levels, or variable declarations inside macros. Default is `false`.
+## Options
+
+```{option} LineThreshold
+Flag functions exceeding this number of lines. Default is `none` (ignore the
+number of lines).
+```
+
+```{option} StatementThreshold
+Flag functions exceeding this number of statements. This may differ
+significantly from the number of lines for macro-heavy code. Default is
+`800`.
+```
+
+```{option} BranchThreshold
+Flag functions exceeding this number of control statements. Default is
+`none` (ignore the number of branches).
+```
+
+```{option} ParameterThreshold
+Flag functions that exceed a specified number of parameters. Default
+is `none` (ignore the number of parameters).
+```
+
+```{option} NestingThreshold
+Flag compound statements which create next nesting level after
+{option}`NestingThreshold`. This may differ significantly from the expected
+value for macro-heavy code. Default is `none` (ignore the nesting level).
+```
+
+```{option} VariableThreshold
+Flag functions exceeding this number of variables declared in the body.
+Please note that function parameters and variables declared in lambdas,
+GNU Statement Expressions, and nested class inline functions are not counted.
+Default is `none` (ignore the number of variables).
+```
+
+```{option} CountMemberInitAsStmt
+When `true`, count class member initializers in constructors as statements.
+Default is `true`.
+```
+
+```{option} IgnoreMacros
+When `true`, the check will not count statements, branches, nesting
+levels, or variable declarations inside macros. Default is `false`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/identifier-length.md b/clang-tools-extra/docs/clang-tidy/checks/readability/identifier-length.md
index 52910ef032f26..080b66a4dbc71 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/identifier-length.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/identifier-length.md
@@ -1,147 +1,148 @@
-.. title:: clang-tidy - readability-identifier-length
+```{title} clang-tidy - readability-identifier-length
+```
-readability-identifier-length
-=============================
+# readability-identifier-length
This check finds variables and function parameters whose length are too short.
The desired name length is configurable. Special short names which should be
ignored can be specified. Local variables with short names can also be ignored
if they are short-lived.
-Options
--------
+## Options
The following options are described below:
- - :option:`MinimumVariableNameLength`, :option:`IgnoredVariableNames`
- - :option:`MinimumBindingNameLength`, :option:`IgnoredBindingNames`
- - :option:`MinimumParameterNameLength`, :option:`IgnoredParameterNames`
- - :option:`MinimumLoopCounterNameLength`, :option:`IgnoredLoopCounterNames`
- - :option:`MinimumExceptionNameLength`,
- :option:`IgnoredExceptionVariableNames`
- - :option:`LineCountThreshold`
-
-.. option:: MinimumVariableNameLength
-
- All variables (other than loop counter, exception names and function
- parameters) are expected to have at least a length of
- `MinimumVariableNameLength` (default is `3`). Setting it to `0` or `1`
- disables the check entirely.
-
- .. code-block:: c++
-
- int i = 42; // warns that 'i' is too short
-
-.. option:: IgnoredVariableNames
-
- Specifies a regular expression for variable names that are
- to be ignored. The default value is empty, thus no names are ignored.
-
-.. option:: MinimumBindingNameLength
-
- All variables introduced by structured bindings are expected to have at
- least a length of `MinimumBindingNameLength` (default is `2`). Setting it
- to `0` or `1` disables the check entirely.
-
- .. code-block:: c++
-
- auto [a] = get_result(); // warns that 'a' is too short
-
-.. option:: IgnoredBindingNames
-
- Specifies a regular expression for variable names introduced by structured
- bindings that are to be ignored. The default value is `^[_]$`, to allow the
- use of the `_` idiom to specify that the value is discarded on purpose.
-
-.. option:: MinimumParameterNameLength
-
- All function parameter names are expected to have a length of at least
- `MinimumParameterNameLength` (default is `3`). Setting it to `0` or `1`
- disables the check entirely.
-
- .. code-block:: c++
-
- int doubler(int x) // warns that x is too short
- {
- return 2 * x;
- }
-
-.. option:: IgnoredParameterNames
-
- Specifies a regular expression for parameters that are to be ignored.
- The default value is `^[n]$` for historical reasons.
-
-.. option:: MinimumLoopCounterNameLength
-
- Loop counter variables are expected to have a length of at least
- `MinimumLoopCounterNameLength` characters (default is `2`). Setting it to
- `0` or `1` disables the check entirely.
-
- .. code-block:: c++
-
- // This warns that 'q' is too short.
- for (int q = 0; q < size; ++ q) {
- // ...
- }
-
-.. option:: IgnoredLoopCounterNames
-
- Specifies a regular expression for counter names that are to be ignored.
- The default value is `^[ijk_]$`; the first three symbols for historical
- reasons and the last one since it is frequently used as a "don't care"
- value, specifically in tools such as Google Benchmark.
-
- .. code-block:: c++
-
- // This does not warn by default, for historical reasons.
- for (int i = 0; i < size; ++ i) {
- // ...
- }
-
-.. option:: MinimumExceptionNameLength
-
- Exception clause variables are expected to have a length of at least
- `MinimumExceptionNameLength` (default is `2`). Setting it to `0` or `1`
- disables the check entirely.
-
- .. code-block:: c++
-
- try {
- // ...
- }
- // This warns that 'e' is too short.
- catch (const std::exception& x) {
- // ...
- }
-
-.. option:: IgnoredExceptionVariableNames
-
- Specifies a regular expression for exception variable names that are to
- be ignored. The default value is `^[e]$` mainly for historical reasons.
-
- .. code-block:: c++
-
- try {
- // ...
- }
- // This does not warn by default, for historical reasons.
- catch (const std::exception& e) {
- // ...
- }
-
-.. option:: LineCountThreshold
-
- Defines the minimum number of lines required between declaration and last
- use for a diagnostic to be issued. The default value for this option is 0,
- which corresponds to all variables being flagged. This option only affects
- the behavior regarding local variables: a warning is always issued when a
- global variable has a short name, because globals can potentially be used
- across multiple files.
-
- .. code-block:: c++
-
- // In this example, a warning will be issued if LineCountThreshold < N
- int a = 0; // First line (declaration line)
- a = 1; // Second line
- // ...
- last_use_of(a); // N-th line
+- {option}`MinimumVariableNameLength`, {option}`IgnoredVariableNames`
+- {option}`MinimumBindingNameLength`, {option}`IgnoredBindingNames`
+- {option}`MinimumParameterNameLength`,
+ [`IgnoredParameterNames`](#readability-identifier-length-ignored-parameter-names)
+- {option}`MinimumLoopCounterNameLength`, {option}`IgnoredLoopCounterNames`
+- {option}`MinimumExceptionNameLength`,
+ {option}`IgnoredExceptionVariableNames`
+- {option}`LineCountThreshold`
+
+````{option} MinimumVariableNameLength
+All variables (other than loop counter, exception names and function
+parameters) are expected to have at least a length of
+{option}`MinimumVariableNameLength`. Setting it to `0` or `1` disables the
+check entirely. Default is `3`.
+
+```c++
+int i = 42; // warns that 'i' is too short
+```
+````
+
+```{option} IgnoredVariableNames
+Specifies a regular expression for variable names that are
+to be ignored. Default is empty string, so no names are ignored.
+```
+
+````{option} MinimumBindingNameLength
+All variables introduced by structured bindings are expected to have at
+least a length of {option}`MinimumBindingNameLength`. Setting it to `0` or `1`
+disables the check entirely. Default is `2`.
+
+```c++
+auto [a] = get_result(); // warns that 'a' is too short
+```
+````
+
+```{option} IgnoredBindingNames
+Specifies a regular expression for variable names introduced by structured
+bindings that are to be ignored. The `^[_]$` value allows the `_` idiom to
+specify that the value is discarded on purpose. Default is `^[_]$`.
+```
+
+````{option} MinimumParameterNameLength
+All function parameter names are expected to have a length of at least
+{option}`MinimumParameterNameLength`. Setting it to `0` or `1` disables the
+check entirely. Default is `3`.
+
+```c++
+int doubler(int x) // warns that x is too short
+{
+ return 2 * x;
+}
+```
+````
+
+(readability-identifier-length-ignored-parameter-names)=
+
+```{option} IgnoredParameterNames
+Specifies a regular expression for parameters that are to be ignored.
+Default is `^[n]$` for historical reasons.
+```
+
+````{option} MinimumLoopCounterNameLength
+Loop counter variables are expected to have a length of at least
+{option}`MinimumLoopCounterNameLength` characters. Setting it to `0` or `1`
+disables the check entirely. Default is `2`.
+
+```c++
+// This warns that 'q' is too short.
+for (int q = 0; q < size; ++ q) {
+ // ...
+}
+```
+````
+
+````{option} IgnoredLoopCounterNames
+Specifies a regular expression for counter names that are to be ignored.
+Default is `^[ijk_]$`; the first three symbols are included for historical
+reasons and the last one since it is frequently used as a "don't care"
+value, specifically in tools such as Google Benchmark.
+
+```c++
+// This does not warn by default, for historical reasons.
+for (int i = 0; i < size; ++ i) {
+ // ...
+}
+```
+````
+
+````{option} MinimumExceptionNameLength
+Exception clause variables are expected to have a length of at least
+{option}`MinimumExceptionNameLength`. Setting it to `0` or `1` disables the
+check entirely. Default is `2`.
+
+```c++
+try {
+ // ...
+}
+// This warns that 'e' is too short.
+catch (const std::exception& x) {
+ // ...
+}
+```
+````
+
+````{option} IgnoredExceptionVariableNames
+Specifies a regular expression for exception variable nam...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/221529
More information about the llvm-branch-commits
mailing list