[llvm-branch-commits] [clang-tools-extra] [clang-tidy][docs] Rewrite readability check docs to Markdown [3/5] (PR #221534)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Sat Sep 5 23:53:32 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 32.41 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/221534.diff
10 Files Affected:
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/misleading-indentation.md (+19-21)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/named-parameter.md (+54-55)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/non-const-parameter.md (+36-38)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/operators-representation.md (+48-51)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/qualified-auto.md (+110-113)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/redundant-access-specifiers.md (+36-39)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/redundant-casting.md (+30-32)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/redundant-control-flow.md (+33-33)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/redundant-declaration.md (+18-19)
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/redundant-inline-specifier.md (+19-20)
``````````diff
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/misleading-indentation.md b/clang-tools-extra/docs/clang-tidy/checks/readability/misleading-indentation.md
index cac55dd8c22b9..8a91c0a094f93 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/misleading-indentation.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/misleading-indentation.md
@@ -1,39 +1,37 @@
-.. title:: clang-tidy - readability-misleading-indentation
+```{title} clang-tidy - readability-misleading-indentation
+```
-readability-misleading-indentation
-==================================
+# readability-misleading-indentation
Correct indentation helps to understand code. Mismatch of the syntactical
structure and the indentation of the code may hide serious problems.
Missing braces can also make it significantly harder to read the code,
therefore it is important to use braces.
-The way to avoid dangling else is to always check that an ``else`` belongs
-to the ``if`` that begins in the same column.
+The way to avoid dangling else is to always check that an `else` belongs
+to the `if` that begins in the same column.
-You can omit braces when your inner part of e.g. an ``if`` statement has only
+You can omit braces when your inner part of e.g. an `if` statement has only
one statement in it. Although in that case you should begin the next statement
-in the same column with the ``if``.
+in the same column with the `if`.
Examples:
-.. code-block:: c++
-
- // Dangling else:
- if (cond1)
- if (cond2)
- foo1();
- else
- foo2(); // Wrong indentation: else belongs to if(cond2) statement.
-
- // Missing braces:
- if (cond1)
+```c++
+// Dangling else:
+if (cond1)
+ if (cond2)
foo1();
- foo2(); // Not guarded by if(cond1).
+else
+ foo2(); // Wrong indentation: else belongs to if(cond2) statement.
+// Missing braces:
+if (cond1)
+ foo1();
+ foo2(); // Not guarded by if(cond1).
+```
-Limitations
------------
+## Limitations
Note that this check only works as expected when the tabs or spaces are used
consistently and not mixed.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/named-parameter.md b/clang-tools-extra/docs/clang-tidy/checks/readability/named-parameter.md
index 2ab19173055b1..8ca01b6932eab 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/named-parameter.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/named-parameter.md
@@ -1,73 +1,72 @@
-.. title:: clang-tidy - readability-named-parameter
+```{title} clang-tidy - readability-named-parameter
+```
-readability-named-parameter
-===========================
+# readability-named-parameter
Find functions with unnamed arguments.
The check implements the following rule originating in the Google C++ Style
Guide:
-https://google.github.io/styleguide/cppguide.html#Function_Declarations_and_Definitions
+<https://google.github.io/styleguide/cppguide.html#Function_Declarations_and_Definitions>
All parameters should have the same name in both the function declaration and
definition. If a parameter is not utilized, its name can be commented out in a
function definition.
-.. code-block:: c++
+```c++
+int doingSomething(int a, int b, int c);
- int doingSomething(int a, int b, int c);
-
- int doingSomething(int a, int b, int /*c*/) {
- // Ok: the third param is not used
- return a + b;
- }
+int doingSomething(int a, int b, int /*c*/) {
+ // Ok: the third param is not used
+ return a + b;
+}
+```
Corresponding cpplint.py check name: `readability/function`.
The check ignores parameters whose types are standard tag types (e.g.
-``std::in_place_t``, ``std::allocator_arg_t``, ``std::nothrow_t``,
+`std::in_place_t`, `std::allocator_arg_t`, `std::nothrow_t`,
iterator tags, lock tags, etc.). The set of ignored types can be customized
-with the :option:`IgnoredTypes` option.
-
-Options
--------
-
-.. option:: InsertPlainNamesInForwardDecls
-
- If set to `true`, the check will insert parameter names without comments for
- forward declarations only. Otherwise, the check will insert parameter names
- as comments (e.g., ``/*param*/``). Default is `false`.
-
-.. option:: IgnoredTypes
-
- A semicolon-separated list of fully-qualified type names whose parameters
- do not need to be named (for example, tag dispatch types, iterator tags,
- etc.). Defaults to the standard tag types:
-
- .. code-block:: text
-
- std::adopt_lock_t
- std::allocator_arg_t
- std::bidirectional_iterator_tag
- std::contiguous_iterator_tag
- std::default_sentinel_t
- std::defer_lock_t
- std::destroying_delete_t
- std::forward_iterator_tag
- std::from_range_t
- std::in_place_index_t
- std::in_place_t
- std::in_place_type_t
- std::input_iterator_tag
- std::nothrow_t
- std::nostopstate_t
- std::nullopt_t
- std::output_iterator_tag
- std::piecewise_construct_t
- std::random_access_iterator_tag
- std::sorted_equivalent_t
- std::sorted_unique_t
- std::try_to_lock_t
- std::unexpect_t
- std::unreachable_sentinel_t
+with the [`IgnoredTypes`](#readability-named-parameter-ignored-types) option.
+
+## Options
+
+```{option} InsertPlainNamesInForwardDecls
+When `true`, the check will insert parameter names without comments for
+forward declarations only. Otherwise, the check will insert parameter names
+as comments (e.g., `/*param*/`). Default is `false`.
+```
+
+(readability-named-parameter-ignored-types)=
+
+```{option} IgnoredTypes
+A semicolon-separated list of fully-qualified type names whose parameters
+do not need to be named (for example, tag dispatch types, iterator tags,
+etc.). The following standard tag types are ignored by default:
+
+- `std::adopt_lock_t`
+- `std::allocator_arg_t`
+- `std::bidirectional_iterator_tag`
+- `std::contiguous_iterator_tag`
+- `std::default_sentinel_t`
+- `std::defer_lock_t`
+- `std::destroying_delete_t`
+- `std::forward_iterator_tag`
+- `std::from_range_t`
+- `std::in_place_index_t`
+- `std::in_place_t`
+- `std::in_place_type_t`
+- `std::input_iterator_tag`
+- `std::nothrow_t`
+- `std::nostopstate_t`
+- `std::nullopt_t`
+- `std::output_iterator_tag`
+- `std::piecewise_construct_t`
+- `std::random_access_iterator_tag`
+- `std::sorted_equivalent_t`
+- `std::sorted_unique_t`
+- `std::try_to_lock_t`
+- `std::unexpect_t`
+- `std::unreachable_sentinel_t`
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/non-const-parameter.md b/clang-tools-extra/docs/clang-tidy/checks/readability/non-const-parameter.md
index 9e71636b1ffad..2788a482b27e2 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/non-const-parameter.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/non-const-parameter.md
@@ -1,51 +1,49 @@
-.. title:: clang-tidy - readability-non-const-parameter
+```{title} clang-tidy - readability-non-const-parameter
+```
-readability-non-const-parameter
-===============================
+# readability-non-const-parameter
The check finds function parameters of a pointer type that could be changed to
point to a constant type instead.
-When ``const`` is used properly, many mistakes can be avoided. Advantages when
-using ``const`` properly:
+When `const` is used properly, many mistakes can be avoided. Advantages when
+using `const` properly:
- prevent unintentional modification of data;
-
- get additional warnings such as using uninitialized data;
-
- make it easier for developers to see possible side effects.
This check is not strict about constness, it only warns when the constness will
make the function interface safer.
-.. code-block:: c++
-
- // warning here; the declaration "const char *p" would make the function
- // interface safer.
- char f1(char *p) {
- return *p;
- }
-
- // no warning; the declaration could be more const "const int * const p" but
- // that does not make the function interface safer.
- int f2(const int *p) {
- return *p;
- }
-
- // no warning; making x const does not make the function interface safer
- int f3(int x) {
- return x;
- }
-
- // no warning; Technically, *p can be const ("const struct S *p"). But making
- // *p const could be misleading. People might think that it's safe to pass
- // const data to this function.
- struct S { int *a; int *b; };
- int f3(struct S *p) {
- *(p->a) = 0;
- }
-
- // no warning; p is referenced by an lvalue.
- void f4(int *p) {
- int &x = *p;
- }
+```c++
+// warning here; the declaration "const char *p" would make the function
+// interface safer.
+char f1(char *p) {
+ return *p;
+}
+
+// no warning; the declaration could be more const "const int * const p" but
+// that does not make the function interface safer.
+int f2(const int *p) {
+ return *p;
+}
+
+// no warning; making x const does not make the function interface safer
+int f3(int x) {
+ return x;
+}
+
+// no warning; Technically, *p can be const ("const struct S *p"). But making
+// *p const could be misleading. People might think that it's safe to pass
+// const data to this function.
+struct S { int *a; int *b; };
+int f3(struct S *p) {
+ *(p->a) = 0;
+}
+
+// no warning; p is referenced by an lvalue.
+void f4(int *p) {
+ int &x = *p;
+}
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/operators-representation.md b/clang-tools-extra/docs/clang-tidy/checks/readability/operators-representation.md
index 70cf75b72ff78..6112a26621222 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/operators-representation.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/operators-representation.md
@@ -1,63 +1,60 @@
-.. title:: clang-tidy - readability-operators-representation
+```{title} clang-tidy - readability-operators-representation
+```
-readability-operators-representation
-====================================
+# readability-operators-representation
Enforces consistent token representation for invoked binary, unary and
overloaded operators in C++ code. The check supports both traditional and
-alternative representations of operators, such as ``&&`` and ``and``, ``||``
-and ``or``, and so on.
+alternative representations of operators, such as `&&` and `and`, `||`
+and `or`, and so on.
In the realm of C++ programming, developers have the option to choose between
two distinct representations for operators: traditional token representation
and alternative token representation. Traditional tokens utilize symbols,
-such as ``&&``, ``||``, and ``!``, while alternative tokens employ more
-descriptive words like ``and``, ``or``, and ``not``.
+such as `&&`, `||`, and `!`, while alternative tokens employ more
+descriptive words like `and`, `or`, and `not`.
In the following mapping table, a comprehensive list of traditional and
alternative tokens, along with their corresponding representations,
is presented:
-.. table:: Token Representation Mapping Table
- :widths: auto
+```{table} Token Representation Mapping Table
+:widths: auto
- =========== ===========
- Traditional Alternative
- =========== ===========
- ``&&`` ``and``
- ``&=`` ``and_eq``
- ``&`` ``bitand``
- ``|`` ``bitor``
- ``~`` ``compl``
- ``!`` ``not``
- ``!=`` ``not_eq``
- ``||`` ``or``
- ``|=`` ``or_eq``
- ``^`` ``xor``
- ``^=`` ``xor_eq``
- =========== ===========
+| Traditional | Alternative |
+| ----------- | ----------- |
+| `&&` | `and` |
+| `&=` | `and_eq` |
+| `&` | `bitand` |
+| `\|` | `bitor` |
+| `~` | `compl` |
+| `!` | `not` |
+| `!=` | `not_eq` |
+| `\|\|` | `or` |
+| `\|=` | `or_eq` |
+| `^` | `xor` |
+| `^=` | `xor_eq` |
+```
-Example
--------
+## Example
-.. code-block:: c++
+```c++
+// Traditional Token Representation:
- // Traditional Token Representation:
+if (!a||!b)
+{
+ // do something
+}
- if (!a||!b)
- {
- // do something
- }
+// Alternative Token Representation:
- // Alternative Token Representation:
+if (not a or not b)
+{
+ // do something
+}
+```
- if (not a or not b)
- {
- // do something
- }
-
-Options
--------
+## Options
Due to the distinct benefits and drawbacks of each representation, the default
configuration doesn't enforce either. Explicit configuration is needed.
@@ -74,14 +71,14 @@ representations as desired by specifying a semicolon-separated list of
both traditional and alternative tokens in the configuration,
such as `and;||;not`.
-.. option:: BinaryOperators
-
- This option allows you to specify a semicolon-separated list of binary
- operators for which you want to enforce specific token representation.
- The default value is empty string.
-
-.. option:: OverloadedOperators
-
- This option allows you to specify a semicolon-separated list of overloaded
- operators for which you want to enforce specific token representation.
- The default value is empty string.
+```{option} BinaryOperators
+This option allows you to specify a semicolon-separated list of binary
+operators for which you want to enforce specific token representation.
+Default is empty string.
+```
+
+```{option} OverloadedOperators
+This option allows you to specify a semicolon-separated list of overloaded
+operators for which you want to enforce specific token representation.
+Default is empty string.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/qualified-auto.md b/clang-tools-extra/docs/clang-tidy/checks/readability/qualified-auto.md
index d031b677d7618..a7c64a501fbad 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/qualified-auto.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/qualified-auto.md
@@ -1,141 +1,138 @@
-.. title:: clang-tidy - readability-qualified-auto
+```{title} clang-tidy - readability-qualified-auto
+```
-readability-qualified-auto
-==========================
+# readability-qualified-auto
-Adds pointer qualifications to ``auto``-typed variables that are deduced to
+Adds pointer qualifications to `auto`-typed variables that are deduced to
pointers.
-`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html#beware-unnecessary-copies-with-auto>`_
-advises to make it obvious if a ``auto`` typed variable is a pointer. This
-check will transform ``auto`` to ``auto *`` when the type is deduced to be a
+[LLVM Coding Standards](https://llvm.org/docs/CodingStandards.html#beware-unnecessary-copies-with-auto)
+advises to make it obvious if a `auto` typed variable is a pointer. This
+check will transform `auto` to `auto *` when the type is deduced to be a
pointer.
-.. code-block:: c++
-
- for (auto Data : MutatablePtrContainer) {
- change(*Data);
- }
- for (auto Data : ConstantPtrContainer) {
- observe(*Data);
- }
+```c++
+for (auto Data : MutatablePtrContainer) {
+ change(*Data);
+}
+for (auto Data : ConstantPtrContainer) {
+ observe(*Data);
+}
+```
Would be transformed into:
-.. code-block:: c++
-
- for (auto *Data : MutatablePtrContainer) {
- change(*Data);
- }
- for (const auto *Data : ConstantPtrContainer) {
- observe(*Data);
- }
-
-Note ``const`` ``volatile`` qualified types will retain their ``const`` and
-``volatile`` qualifiers. Pointers to pointers will not be fully qualified.
-
-.. code-block:: c++
-
- const auto Foo = cast<int *>(Baz1);
- const auto Bar = cast<const int *>(Baz2);
- volatile auto FooBar = cast<int *>(Baz3);
- auto BarFoo = cast<int **>(Baz4);
+```c++
+for (auto *Data : MutatablePtrContainer) {
+ change(*Data);
+}
+for (const auto *Data : ConstantPtrContainer) {
+ observe(*Data);
+}
+```
+
+Note `const` `volatile` qualified types will retain their `const` and
+`volatile` qualifiers. Pointers to pointers will not be fully qualified.
+
+```c++
+const auto Foo = cast<int *>(Baz1);
+const auto Bar = cast<const int *>(Baz2);
+volatile auto FooBar = cast<int *>(Baz3);
+auto BarFoo = cast<int **>(Baz4);
+```
Would be transformed into:
-.. code-block:: c++
-
- auto *const Foo = cast<int *>(Baz1);
- const auto *const Bar = cast<const int *>(Baz2);
- auto *volatile FooBar = cast<int *>(Baz3);
- auto *BarFoo = cast<int **>(Baz4);
-
-Options
--------
-
-.. option:: AddConstToQualified
+```c++
+auto *const Foo = cast<int *>(Baz1);
+const auto *const Bar = cast<const int *>(Baz2);
+auto *volatile FooBar = cast<int *>(Baz3);
+auto *BarFoo = cast<int **>(Baz4);
+```
- When set to `true` the check will add const qualifiers variables defined as
- ``auto *`` or ``auto &`` when applicable.
- Default value is `true`.
+## Options
-.. code-block:: c++
+```{option} AddConstToQualified
+When `true`, the check will add const qualifiers to variables defined as
+`auto *` or `auto &` when applicable.
+Default is `true`.
+```
- auto Foo1 = cast<const int *>(Bar1);
- auto *Foo2 = cast<const int *>(Bar2);
- auto &Foo3 = cast<const int &>(Bar3);
+```c++
+auto Foo1 = cast<const int *>(Bar1);
+auto *Foo2 = cast<const int *>(Bar2);
+auto &Foo3 = cast<const int &>(Bar3);
+```
-If AddConstToQualified is set to `false`, it will be transformed into:
+If {option}`AddConstToQualified` is set to `false`, it will be transformed into:
-.. code-block:: c++
-
- const auto *Foo1 = cast<const int *>(Bar1);
- auto *Foo2 = cast<const int *>(Bar2);
- auto &Foo3 = cast<const int &>(Bar3);
+```c++
+const auto *Foo1 = cast<const int *>(Bar1);
+auto *Foo2 = cast<const int *>(Bar2);
+auto &Foo3 = cast<const int &>(Bar3);
+```
Otherwise it will be transformed into:
-.. code-block:: c++
-
- const auto *Foo1 = cast<const int *>(Bar1);
- const auto *Foo2 = cast<const int *>(Bar2);
- const auto &Foo3 = cast<const int &>(Bar3);
-
-Note in the LLVM alias, the default value is `false`.
-
-.. option:: AllowedTypes
-
- A semicolon-separated list of names of types to ignore when ``auto`` is
- deduced to that type or a pointer to that type. Note that this distinguishes
- type aliases from the original type, so specifying e.g. ``my_int`` will not
- suppress reports about ``int`` even if it is defined as a ``typedef`` alias
- for ``int``. Regular expressions are accepted, e.g. ``[Rr]ef(erence)?$``
- matches every type with suffix ``Ref``, ``ref``, ``Reference`` and
- ``reference``. 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``). E.g. to suppress reports
- for ``std::array`` iterators use `std::array<.*>::(const_)?iterator` string.
- The default is an empty string.
-
-.. option:: IgnoreAliasing
-
- If set to `true` the check will use the underlying type to determine the type
- that ``auto`` is deduced to. If set to `false` the check will not look beyond
- the first type alias.
- Default value is `true`.
-
- .. code-block:: c++
-
- using IntPtr = int*;
- IntPtr foo();
-
- auto bar = foo();
-
- If :option:`IgnoreAliasing` is set to `true`, it will be transformed into:
-
- .. code-block:: c++
-
- auto *bar = foo();
-
- Otherwise no changes will occur.
-
-
-Limitations
------------
-
-When :option:`IgnoreAliasing` is set to `false`, there are cases where
+```c++
+const auto *Foo1 = cast<const int *>(Bar1);
+const auto *Foo2 = cast<const int *>(Bar2);
+const auto &Foo3 = cast<const int &>(Bar3);
+```
+
+For the `llvm-qualified-auto` alias, default is `false`.
+
+```{option} AllowedTypes
+A semicolon-separated list of names of types to ignore when `auto` is
+deduced to that type or a pointer to that type. Note that this distinguishes
+type aliases from the original type, so specifying e.g. `my_int` will not
+suppress reports about `int` even if it is defined as a `typedef` alias
+for `int`. Regular expressions are accepted, e.g. `[Rr]ef(erence)?$`
+matches every type with suffix `Ref`, `ref`, `Reference` and
+`reference`. 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`). E.g. to suppress reports
+for `std::array` iterators use `std::array<.*>::(const_)?iterator` string.
+Default is an empty string.
+```
+
+````{option} IgnoreAl...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/221534
More information about the llvm-branch-commits
mailing list