[llvm-branch-commits] [clang-tools-extra] [clang-tidy][docs] Rewrite readability check docs to Markdown [1/5] (PR #221447)
Zeyi Xu via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Sat Sep 5 21:09:36 PDT 2026
https://github.com/zeyi2 updated https://github.com/llvm/llvm-project/pull/221447
>From b59cce1e8b19cb01994236205c1131309ca11895 Mon Sep 17 00:00:00 2001
From: Zeyi Xu <mitchell.xu2 at gmail.com>
Date: Sat, 5 Sep 2026 22:10:05 +0800
Subject: [PATCH 1/2] [clang-tidy][docs] Rewrite readability check docs to
Markdown [1/5]
---
.../ambiguous-smartptr-reset-call.md | 90 +++++----
.../avoid-return-with-void-value.md | 64 +++---
.../avoid-unconditional-preprocessor-if.md | 32 +--
.../readability/braces-around-statements.md | 47 +++--
.../checks/readability/const-return-type.md | 42 ++--
.../checks/readability/container-contains.md | 48 +++--
.../readability/container-size-empty.md | 52 +++--
.../checks/readability/duplicate-include.md | 57 +++---
.../checks/readability/else-after-return.md | 137 ++++++-------
.../checks/readability/enum-initial-value.md | 191 +++++++++---------
10 files changed, 372 insertions(+), 388 deletions(-)
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/ambiguous-smartptr-reset-call.md b/clang-tools-extra/docs/clang-tidy/checks/readability/ambiguous-smartptr-reset-call.md
index f8df02dd4460e..5d757ae88cae1 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/ambiguous-smartptr-reset-call.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/ambiguous-smartptr-reset-call.md
@@ -1,62 +1,64 @@
-.. title:: clang-tidy - readability-ambiguous-smartptr-reset-call
+```{title} clang-tidy - readability-ambiguous-smartptr-reset-call
+```
-readability-ambiguous-smartptr-reset-call
-=========================================
+# readability-ambiguous-smartptr-reset-call
-Finds potentially erroneous calls to ``reset`` method on smart pointers when
-the pointee type also has a ``reset`` method. Having a ``reset`` method in
+Finds potentially erroneous calls to `reset` method on smart pointers when
+the pointee type also has a `reset` method. Having a `reset` method in
both classes makes it easy to accidentally make the pointer null when
intending to reset the underlying object.
-.. code-block:: c++
+```c++
+struct Resettable {
+ void reset() { /* Own reset logic */ }
+};
- struct Resettable {
- void reset() { /* Own reset logic */ }
- };
+auto ptr = std::make_unique<Resettable>();
- auto ptr = std::make_unique<Resettable>();
-
- ptr->reset(); // Calls underlying reset method
- ptr.reset(); // Makes the pointer null
+ptr->reset(); // Calls underlying reset method
+ptr.reset(); // Makes the pointer null
+```
Both calls are valid C++ code, but the second one might not be what the
developer intended, as it destroys the pointed-to object rather than resetting
its state. It's easy to make such a typo because the difference between
-``.`` and ``->`` is really small.
+`.` and `->` is really small.
The recommended approach is to make the intent explicit by using either member
access or direct assignment:
-.. code-block:: c++
-
- std::unique_ptr<Resettable> ptr = std::make_unique<Resettable>();
+```c++
+std::unique_ptr<Resettable> ptr = std::make_unique<Resettable>();
- (*ptr).reset(); // Clearly calls underlying reset method
- ptr = nullptr; // Clearly makes the pointer null
+(*ptr).reset(); // Clearly calls underlying reset method
+ptr = nullptr; // Clearly makes the pointer null
+```
The default smart pointers and classes that are considered are
-``std::unique_ptr``, ``std::shared_ptr``, ``boost::shared_ptr``. To specify
-other smart pointers or other classes use the :option:`SmartPointers` option.
-
-
-.. note::
-
- The check may emit invalid fix-its and misleading warning messages when
- specifying custom smart pointers or other classes in the
- :option:`SmartPointers` option. For example, ``boost::scoped_ptr`` does not
- have an ``operator=`` which makes fix-its invalid.
-
-.. note::
-
- Automatic fix-its are enabled only if :program:`clang-tidy` is invoked with
- the `--fix-notes` option.
-
-
-Options
--------
-
-.. option:: SmartPointers
-
- Semicolon-separated list of fully qualified class names of custom smart
- pointers. Default value is `::std::unique_ptr;::std::shared_ptr;
- ::boost::shared_ptr`.
+`std::unique_ptr`, `std::shared_ptr`, `boost::shared_ptr`. To specify
+other smart pointers or other classes use the
+[`SmartPointers`](#readability-ambiguous-smartptr-reset-call-smart-pointers)
+option.
+
+```{note}
+The check may emit invalid fix-its and misleading warning messages when
+specifying custom smart pointers or other classes in the
+[`SmartPointers`](#readability-ambiguous-smartptr-reset-call-smart-pointers)
+option. For example, `boost::scoped_ptr` does not
+have an `operator=` which makes fix-its invalid.
+```
+
+```{note}
+Automatic fix-its are enabled only if {program}`clang-tidy` is invoked with
+the `--fix-notes` option.
+```
+
+## Options
+
+(readability-ambiguous-smartptr-reset-call-smart-pointers)=
+
+```{option} SmartPointers
+Semicolon-separated list of fully qualified class names of custom smart
+pointers. Default is
+`::std::unique_ptr;::std::shared_ptr;::boost::shared_ptr`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-return-with-void-value.md b/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-return-with-void-value.md
index b07958188d313..6733a2bf9bdde 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-return-with-void-value.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-return-with-void-value.md
@@ -1,51 +1,49 @@
-.. title:: clang-tidy - readability-avoid-return-with-void-value
+```{title} clang-tidy - readability-avoid-return-with-void-value
+```
-readability-avoid-return-with-void-value
-========================================
+# readability-avoid-return-with-void-value
-Finds return statements with ``void`` values used within functions with
-``void`` result types.
+Finds return statements with `void` values used within functions with
+`void` result types.
-A function with a ``void`` return type is intended to perform a task without
+A function with a `void` return type is intended to perform a task without
producing a return value. Return statements with expressions could lead
to confusion and may miscommunicate the function's intended behavior.
Example:
-.. code-block::
+```
+void g();
+void f() {
+ // ...
+ return g();
+}
+```
- void g();
- void f() {
- // ...
- return g();
- }
-
-In a long function body, the ``return`` statement suggests that the function
-returns a value. However, ``return g();`` is a combination of two statements
+In a long function body, the `return` statement suggests that the function
+returns a value. However, `return g();` is a combination of two statements
that should be written as
-.. code-block::
-
- g();
- return;
+```
+g();
+return;
+```
-to make clear that ``g()`` is called and immediately afterwards the function
+to make clear that `g()` is called and immediately afterwards the function
returns (nothing).
-In C, the same issue is detected by the compiler if the ``-Wpedantic`` mode
+In C, the same issue is detected by the compiler if the `-Wpedantic` mode
is enabled.
-Options
--------
-
-.. option:: IgnoreMacros
-
- The value `false` specifies that return statements expanded
- from macros are not checked. The default value is `true`.
+## Options
-.. option:: StrictMode
+```{option} IgnoreMacros
+When `false`, return statements expanded from macros are not checked.
+Default is `true`.
+```
- The value `false` specifies that a direct return statement shall
- be excluded from the analysis if it is the only statement not
- contained in a block, like ``if (cond) return g();``. The default
- value is `true`.
+```{option} StrictMode
+When `false`, a direct return statement is excluded from the analysis if it is
+the only statement not contained in a block, like
+`if (cond) return g();`. Default is `true`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-unconditional-preprocessor-if.md b/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-unconditional-preprocessor-if.md
index ce3bfaffac380..87e814a085227 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-unconditional-preprocessor-if.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-unconditional-preprocessor-if.md
@@ -1,32 +1,32 @@
-.. title:: clang-tidy - readability-avoid-unconditional-preprocessor-if
+```{title} clang-tidy - readability-avoid-unconditional-preprocessor-if
+```
-readability-avoid-unconditional-preprocessor-if
-===============================================
+# readability-avoid-unconditional-preprocessor-if
Finds code blocks that are constantly enabled or disabled in preprocessor
-directives by analyzing ``#if`` conditions, such as ``#if 0`` and ``#if 1``,
+directives by analyzing `#if` conditions, such as `#if 0` and `#if 1`,
etc.
-.. code-block:: c++
+```c++
+#if 0
+ // some disabled code
+#endif
- #if 0
- // some disabled code
- #endif
+#if 1
+ // some enabled code that can be disabled manually
+#endif
+```
- #if 1
- // some enabled code that can be disabled manually
- #endif
-
-Unconditional preprocessor directives, such as ``#if 0`` for disabled code
-and ``#if 1`` for enabled code, can lead to dead code and always enabled code,
+Unconditional preprocessor directives, such as `#if 0` for disabled code
+and `#if 1` for enabled code, can lead to dead code and always enabled code,
respectively. Dead code can make understanding the codebase more difficult,
hinder readability, and may be a sign of unfinished functionality or abandoned
features. This can cause maintenance issues, confusion for future developers,
and potential compilation problems.
As a solution for both cases, consider using preprocessor macros or defines,
-like ``#ifdef DEBUGGING_ENABLED``, to control code enabling or disabling.
+like `#ifdef DEBUGGING_ENABLED`, to control code enabling or disabling.
This approach provides better coordination and flexibility when working with
different parts of the codebase. Alternatively, you can comment out the entire
-code using ``/* */`` block comments and add a hint, such as ``@todo``,
+code using `/* */` block comments and add a hint, such as `@todo`,
to indicate future actions.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/braces-around-statements.md b/clang-tools-extra/docs/clang-tidy/checks/readability/braces-around-statements.md
index 2c0816591eb98..a8e4e62ace963 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/braces-around-statements.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/braces-around-statements.md
@@ -1,38 +1,37 @@
-.. title:: clang-tidy - readability-braces-around-statements
+```{title} clang-tidy - readability-braces-around-statements
+```
-readability-braces-around-statements
-====================================
+# readability-braces-around-statements
`google-readability-braces-around-statements` redirects here as an alias for
this check.
-Checks that bodies of ``if`` statements and loops (``for``, ``do while``, and
-``while``) are inside braces.
+Checks that bodies of `if` statements and loops (`for`, `do while`, and
+`while`) are inside braces.
Before:
-.. code-block:: c++
-
- if (condition)
- statement;
+```c++
+if (condition)
+ statement;
+```
After:
-.. code-block:: c++
-
- if (condition) {
- statement;
- }
-
-Options
--------
+```c++
+if (condition) {
+ statement;
+}
+```
-.. option:: ShortStatementLines
+## Options
- Defines the minimal number of lines that the statement should have in order
- to trigger this check.
+```{option} ShortStatementLines
+Defines the minimal number of lines that the statement should have in order
+to trigger this check.
- The number of lines is counted from the end of condition or initial keyword
- (``do``/``else``) until the last line of the inner statement. Default value
- `0` means that braces will be added to all statements (not having them
- already).
+The number of lines is counted from the end of condition or initial keyword
+(`do`/`else`) until the last line of the inner statement. A value of `0` means
+that braces will be added to all statements that do not already have them.
+Default is `0`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/const-return-type.md b/clang-tools-extra/docs/clang-tidy/checks/readability/const-return-type.md
index ec81d46750d44..1d86ccbac2cce 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/const-return-type.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/const-return-type.md
@@ -1,35 +1,33 @@
-.. title:: clang-tidy - readability-const-return-type
+```{title} clang-tidy - readability-const-return-type
+```
-readability-const-return-type
-=============================
+# readability-const-return-type
-Checks for functions with a ``const``-qualified return type and recommends
-removal of the ``const`` keyword. Such use of `const` is usually superfluous,
+Checks for functions with a `const`-qualified return type and recommends
+removal of the `const` keyword. Such use of `const` is usually superfluous,
and can prevent valuable compiler optimizations. Does not (yet) fix trailing
return types.
Examples:
-.. code-block:: c++
-
- const int foo();
- const Clazz foo();
- Clazz *const foo();
+```c++
+const int foo();
+const Clazz foo();
+Clazz *const foo();
+```
Note that this applies strictly to top-level qualification, which excludes
pointers or references to const values. For example, these are fine:
-.. code-block:: c++
-
- const int* foo();
- const int& foo();
- const Clazz* foo();
-
-
-Options
--------
+```c++
+const int* foo();
+const int& foo();
+const Clazz* foo();
+```
-.. option:: IgnoreMacros
+## Options
- If set to `true`, the check will not give warnings inside macros. Default
- is `true`.
+```{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/container-contains.md b/clang-tools-extra/docs/clang-tidy/checks/readability/container-contains.md
index 120d360ab5841..bd12584376cb4 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/container-contains.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/container-contains.md
@@ -1,34 +1,32 @@
-.. title:: clang-tidy - readability-container-contains
+```{title} clang-tidy - readability-container-contains
+```
-readability-container-contains
-==============================
+# readability-container-contains
-Finds usages of ``container.count()`` and
-``container.find() == container.end()`` which should be replaced by a call to
-the ``container.contains()`` method.
+Finds usages of `container.count()` and
+`container.find() == container.end()` which should be replaced by a call to
+the `container.contains()` method.
Whether an element is contained inside a container should be checked with
-``contains`` instead of ``count``/``find`` because ``contains`` conveys the
+`contains` instead of `count`/`find` because `contains` conveys the
intent more clearly. Furthermore, for containers which permit multiple entries
-per key (``multimap``, ``multiset``, ...), ``contains`` is more efficient than
-``count`` because ``count`` has to do unnecessary additional work.
+per key (`multimap`, `multiset`, ...), `contains` is more efficient than
+`count` because `count` has to do unnecessary additional work.
Examples:
-====================================== =====================================
-Initial expression Result
--------------------------------------- -------------------------------------
-``myMap.find(x) == myMap.end()`` ``!myMap.contains(x)``
-``myMap.find(x) != myMap.end()`` ``myMap.contains(x)``
-``myStr.find(x) != std::string::npos`` ``myStr.contains(x)``
-``if (myMap.count(x))`` ``if (myMap.contains(x))``
-``bool exists = myMap.count(x)`` ``bool exists = myMap.contains(x)``
-``bool exists = myMap.count(x) > 0`` ``bool exists = myMap.contains(x)``
-``bool exists = myMap.count(x) >= 1`` ``bool exists = myMap.contains(x)``
-``bool missing = myMap.count(x) == 0`` ``bool missing = !myMap.contains(x)``
-====================================== =====================================
+| Initial expression | Result |
+|--------------------------------------|-------------------------------------|
+| `myMap.find(x) == myMap.end()` | `!myMap.contains(x)` |
+| `myMap.find(x) != myMap.end()` | `myMap.contains(x)` |
+| `myStr.find(x) != std::string::npos` | `myStr.contains(x)` |
+| `if (myMap.count(x))` | `if (myMap.contains(x))` |
+| `bool exists = myMap.count(x)` | `bool exists = myMap.contains(x)` |
+| `bool exists = myMap.count(x) > 0` | `bool exists = myMap.contains(x)` |
+| `bool exists = myMap.count(x) >= 1` | `bool exists = myMap.contains(x)` |
+| `bool missing = myMap.count(x) == 0` | `bool missing = !myMap.contains(x)` |
-This check will apply to any class that has a ``contains`` method, notably
-including ``std::set``, ``std::unordered_set``, ``std::map``, and
-``std::unordered_map`` as of C++20, and ``std::string`` and
-``std::string_view`` as of C++23.
+This check will apply to any class that has a `contains` method, notably
+including `std::set`, `std::unordered_set`, `std::map`, and
+`std::unordered_map` as of C++20, and `std::string` and
+`std::string_view` as of C++23.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/container-size-empty.md b/clang-tools-extra/docs/clang-tidy/checks/readability/container-size-empty.md
index 70b05f498d804..89b5f9fbbc886 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/container-size-empty.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/container-size-empty.md
@@ -1,37 +1,35 @@
-.. title:: clang-tidy - readability-container-size-empty
+```{title} clang-tidy - readability-container-size-empty
+```
-readability-container-size-empty
-================================
+# readability-container-size-empty
+Checks whether a call to the `size()`/`length()` method or the
+`std::size()` free function can be replaced with a call to `empty()`.
-Checks whether a call to the ``size()``/``length()`` method or the
-``std::size()`` free function can be replaced with a call to ``empty()``.
-
-The emptiness of a container should be checked using the ``empty()`` method
-instead of the ``size()``/``length()`` method or ``std::size()``. It shows
-clearer intent to use ``empty()``. Furthermore some containers (for example, a
-``std::forward_list``) may implement the ``empty()`` method but not implement
-the ``size()`` or ``length()`` method. Using ``empty()`` whenever possible
+The emptiness of a container should be checked using the `empty()` method
+instead of the `size()`/`length()` method or `std::size()`. It shows
+clearer intent to use `empty()`. Furthermore some containers (for example, a
+`std::forward_list`) may implement the `empty()` method but not implement
+the `size()` or `length()` method. Using `empty()` whenever possible
makes it easier to switch to another container in the future.
-The check issues warning if a container has ``empty()`` and ``size()`` or
-``length()`` methods matching following signatures:
-
-.. code-block:: c++
+The check issues warning if a container has `empty()` and `size()` or
+`length()` methods matching following signatures:
- size_type size() const;
- size_type length() const;
- bool empty() const;
+```c++
+size_type size() const;
+size_type length() const;
+bool empty() const;
+```
`size_type` can be any kind of integer type.
-Options
--------
-
-.. option:: ExcludedComparisonTypes
+## Options
- A semicolon-separated list of regular expressions matching class names for
- which the check will ignore comparisons of objects with default-constructed
- objects of the same type. If a class is listed here, the check will not
- suggest using ``empty()`` instead of such comparisons for objects of that
- class. Default value is: `::std::array`.
+```{option} ExcludedComparisonTypes
+A semicolon-separated list of regular expressions matching class names for
+which the check will ignore comparisons of objects with default-constructed
+objects of the same type. If a class is listed here, the check will not
+suggest using `empty()` instead of such comparisons for objects of that
+class. Default is `::std::array`.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/duplicate-include.md b/clang-tools-extra/docs/clang-tidy/checks/readability/duplicate-include.md
index 28a4991a922f8..5ff274157eff7 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/duplicate-include.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/duplicate-include.md
@@ -1,44 +1,43 @@
-.. title:: clang-tidy - readability-duplicate-include
+```{title} clang-tidy - readability-duplicate-include
+```
-readability-duplicate-include
-=============================
+# readability-duplicate-include
-Looks for duplicate includes and removes them. The check maintains a list of
-included files and looks for duplicates. If a macro is defined or undefined
+Looks for duplicate includes and removes them. The check maintains a list of
+included files and looks for duplicates. If a macro is defined or undefined
then the list of included files is cleared.
Examples:
-.. code-block:: c++
-
- #include <memory>
- #include <vector>
- #include <memory>
+```c++
+#include <memory>
+#include <vector>
+#include <memory>
+```
becomes
-.. code-block:: c++
-
- #include <memory>
- #include <vector>
+```c++
+#include <memory>
+#include <vector>
+```
Because of the intervening macro definitions, this code remains unchanged:
-.. code-block:: c++
-
- #undef NDEBUG
- #include "assertion.h"
- // ...code with assertions enabled
-
- #define NDEBUG
- #include "assertion.h"
- // ...code with assertions disabled
+```c++
+#undef NDEBUG
+#include "assertion.h"
+// ...code with assertions enabled
-Options
--------
+#define NDEBUG
+#include "assertion.h"
+// ...code with assertions disabled
+```
-.. option:: IgnoredFilesList
+## Options
- A semicolon-separated list of regular expressions or filenames that are
- allowed to be included multiple times without diagnostics. Matching is
- performed against the textual include name. Default is an empty string.
+```{option} IgnoredFilesList
+A semicolon-separated list of regular expressions or filenames that are
+allowed to be included multiple times without diagnostics. Matching is
+performed against the textual include name. Default is an empty string.
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md b/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md
index 569fa24d81c49..459fcde377240 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md
@@ -1,90 +1,85 @@
-.. title:: clang-tidy - readability-else-after-return
+```{title} clang-tidy - readability-else-after-return
+```
-readability-else-after-return
-=============================
+# readability-else-after-return
-`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_ advises to
+[LLVM Coding Standards](https://llvm.org/docs/CodingStandards.html) advises to
reduce indentation where possible and where it makes understanding code easier.
Early exit is one of the suggested enforcements of that. Please do not use
-``else`` or ``else if`` after something that interrupts control flow - like
-``return``, ``break``, ``continue``, ``throw``.
+`else` or `else if` after something that interrupts control flow - like
+`return`, `break`, `continue`, `throw`.
The following piece of code illustrates how the check works.
This piece of code:
-.. code-block:: c++
-
- void foo(int Value) {
- int Local = 0;
- for (int i = 0; i < 42; i++) {
- if (Value == 1) {
- return;
- } else {
- Local++;
- }
-
- if (Value == 2)
- continue;
- else
- Local++;
-
- if (Value == 3) {
- throw 42;
- } else {
- Local++;
- }
- }
+```c++
+void foo(int Value) {
+ int Local = 0;
+ for (int i = 0; i < 42; i++) {
+ if (Value == 1) {
+ return;
+ } else {
+ Local++;
}
+ if (Value == 2)
+ continue;
+ else
+ Local++;
-Would be transformed into:
-
-.. code-block:: c++
-
- void foo(int Value) {
- int Local = 0;
- for (int i = 0; i < 42; i++) {
- if (Value == 1) {
- return;
- }
- Local++;
-
- if (Value == 2)
- continue;
- Local++;
-
- if (Value == 3) {
- throw 42;
- }
- Local++;
- }
+ if (Value == 3) {
+ throw 42;
+ } else {
+ Local++;
}
+ }
+}
+```
-Options
--------
-
-.. option:: WarnOnUnfixable
-
- When `true`, emit a warning for cases where the check can't output a
- Fix-It. These can occur with declarations inside the ``else`` branch that
- would have an extended lifetime if the ``else`` branch was removed.
- Default value is `true`.
-
-.. option:: WarnOnConditionVariables
+Would be transformed into:
- When `true`, the check will attempt to refactor a variable defined inside
- the condition of the ``if`` statement that is used in the ``else`` branch
- defining them just before the ``if`` statement. This can only be done if
- the ``if`` statement is the last statement in its parent's scope.
- Default value is `true`.
+```c++
+void foo(int Value) {
+ int Local = 0;
+ for (int i = 0; i < 42; i++) {
+ if (Value == 1) {
+ return;
+ }
+ Local++;
+ if (Value == 2)
+ continue;
+ Local++;
-LLVM alias
-----------
+ if (Value == 3) {
+ throw 42;
+ }
+ Local++;
+ }
+}
+```
+
+## Options
+
+```{option} WarnOnUnfixable
+When `true`, emit a warning for cases where the check can't output a
+Fix-It. These can occur with declarations inside the `else` branch that
+would have an extended lifetime if the `else` branch was removed.
+Default is `true`.
+```
+
+```{option} WarnOnConditionVariables
+When `true`, the check will attempt to refactor a variable defined inside
+the condition of the `if` statement that is used in the `else` branch
+defining them just before the `if` statement. This can only be done if
+the `if` statement is the last statement in its parent's scope.
+Default is `true`.
+```
+
+## LLVM alias
There is an alias of this check called llvm-else-after-return.
-In that version the options :option:`WarnOnUnfixable` and
-:option:`WarnOnConditionVariables` are both set to `false` by default.
+In that version the options {option}`WarnOnUnfixable` and
+{option}`WarnOnConditionVariables` are both set to `false` by default.
-This check helps to enforce this `LLVM Coding Standards recommendation
-<https://llvm.org/docs/CodingStandards.html#don-t-use-else-after-a-return>`_.
+This check helps to enforce this [LLVM Coding Standards recommendation](https://llvm.org/docs/CodingStandards.html#don-t-use-else-after-a-return).
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.md b/clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.md
index 8ca8ee7fe3569..aec3af8c11eec 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.md
@@ -1,7 +1,7 @@
-.. title:: clang-tidy - readability-enum-initial-value
+```{title} clang-tidy - readability-enum-initial-value
+```
-readability-enum-initial-value
-==============================
+# readability-enum-initial-value
Enforces consistent style for enumerators' initialization, covering three
styles: none, first only, or all initialized explicitly.
@@ -12,100 +12,97 @@ enumerators that obtain their integer representation implicitly.
The following three cases are accepted:
-#. **No** enumerators are explicit initialized.
-#. Exactly **the first** enumerator is explicit initialized.
-#. **All** enumerators are explicit initialized.
-
-.. code-block:: c++
-
- enum A { // (1) Valid, none of enumerators are initialized.
- a0,
- a1,
- a2,
- };
-
- enum B { // (2) Valid, the first enumerator is initialized.
- b0 = 0,
- b1,
- b2,
- };
-
- enum C { // (3) Valid, all of enumerators are initialized.
- c0 = 0,
- c1 = 1,
- c2 = 2,
- };
-
- enum D { // warning: initial values in enum 'D' are not consistent,
- // consider explicit initialization of all, none or only
- // the first enumerator
- d0 = 0,
- d1, // note: uninitialized enumerator 'd1' defined here
- d2 = 2,
- };
-
- enum E { // warning: initial values in enum 'E' are not consistent,
- // consider explicit initialization of all, none or only
- // the first enumerator
- e0 = 0,
- e1, // note: uninitialized enumerator 'e1' defined here
- e2 = 2,
- e3, // note: uninitialized enumerator 'e3' defined here
- // Dangerous, as the numeric values of e3 and e5 are both 3,
- // and this is not explicitly visible in the code!
- e4 = 2,
- e5, // note: uninitialized enumerator 'e5' defined here
- };
-
-This check corresponds to the CERT C Coding Standard recommendation `INT09-C. Ensure enumeration constants map to unique values
-<https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/integers-int/int09-c/>`_.
+1. **No** enumerators are explicit initialized.
+2. Exactly **the first** enumerator is explicit initialized.
+3. **All** enumerators are explicit initialized.
+
+```c++
+enum A { // (1) Valid, none of enumerators are initialized.
+ a0,
+ a1,
+ a2,
+};
+
+enum B { // (2) Valid, the first enumerator is initialized.
+ b0 = 0,
+ b1,
+ b2,
+};
+
+enum C { // (3) Valid, all of enumerators are initialized.
+ c0 = 0,
+ c1 = 1,
+ c2 = 2,
+};
+
+enum D { // warning: initial values in enum 'D' are not consistent,
+ // consider explicit initialization of all, none or only
+ // the first enumerator
+ d0 = 0,
+ d1, // note: uninitialized enumerator 'd1' defined here
+ d2 = 2,
+};
+
+enum E { // warning: initial values in enum 'E' are not consistent,
+ // consider explicit initialization of all, none or only
+ // the first enumerator
+ e0 = 0,
+ e1, // note: uninitialized enumerator 'e1' defined here
+ e2 = 2,
+ e3, // note: uninitialized enumerator 'e3' defined here
+ // Dangerous, as the numeric values of e3 and e5 are both 3,
+ // and this is not explicitly visible in the code!
+ e4 = 2,
+ e5, // note: uninitialized enumerator 'e5' defined here
+};
+```
+
+This check corresponds to the CERT C Coding Standard recommendation [INT09-C. Ensure enumeration constants map to unique values](https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/integers-int/int09-c/).
`cert-int09-c` redirects here as an alias of this check.
-Options
--------
-
-.. option:: AllowExplicitZeroFirstInitialValue
-
- If set to `false`, the first enumerator must not be explicitly initialized to
- a literal ``0``.
- Default is `true`.
-
- .. code-block:: c++
-
- enum F {
- f0 = 0, // Not allowed if AllowExplicitZeroFirstInitialValue is false.
- f1,
- f2,
- };
-
-
-.. option:: AllowExplicitSequentialInitialValues
-
- If set to `false`, explicit initialization to sequential values are not
- allowed.
- Default is `true`.
-
- .. code-block:: c++
-
- enum G {
- g0 = 1, // Not allowed if AllowExplicitSequentialInitialValues is false.
- g1 = 2,
- g2 = 3,
- };
-
-.. option:: AllowReferencedInitialValues
-
- If set to `true`, enumerators initialized by referencing another enumerator
- in the same enum are allowed, and the remaining enumerators are checked for
- consistency. This implements the `INT09-C-EX1` exception from the CERT C
- Coding Standard.
- Default is `false`.
-
- .. code-block:: c++
-
- enum H {
- h0,
- h1,
- h2 = h1, // Allowed if AllowReferencedInitialValues is true.
- };
+## Options
+
+````{option} AllowExplicitZeroFirstInitialValue
+When `false`, the first enumerator must not be explicitly initialized to
+a literal `0`.
+Default is `true`.
+
+```c++
+enum F {
+ f0 = 0, // Not allowed if AllowExplicitZeroFirstInitialValue is false.
+ f1,
+ f2,
+};
+```
+````
+
+````{option} AllowExplicitSequentialInitialValues
+When `false`, explicit initialization to sequential values are not
+allowed.
+Default is `true`.
+
+```c++
+enum G {
+ g0 = 1, // Not allowed if AllowExplicitSequentialInitialValues is false.
+ g1 = 2,
+ g2 = 3,
+};
+```
+````
+
+````{option} AllowReferencedInitialValues
+When `true`, enumerators initialized by referencing another enumerator
+in the same enum are allowed, and the remaining enumerators are checked for
+consistency. This implements the `INT09-C-EX1` exception from the CERT C
+Coding Standard.
+Default is `false`.
+
+```c++
+enum H {
+ h0,
+ h1,
+ h2 = h1, // Allowed if AllowReferencedInitialValues is true.
+};
+```
+````
>From ad426ed31aaafb2c90ada86e4c91bb1b3c2fe985 Mon Sep 17 00:00:00 2001
From: Zeyi Xu <mitchell.xu2 at gmail.com>
Date: Sun, 6 Sep 2026 12:09:28 +0800
Subject: [PATCH 2/2] Update
clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md
Co-authored-by: EugeneZelenko <eugene.zelenko at gmail.com>
---
.../docs/clang-tidy/checks/readability/else-after-return.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md b/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md
index 459fcde377240..b6edb8ee2e419 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md
@@ -63,7 +63,7 @@ void foo(int Value) {
```{option} WarnOnUnfixable
When `true`, emit a warning for cases where the check can't output a
-Fix-It. These can occur with declarations inside the `else` branch that
+fix-it. These can occur with declarations inside the `else` branch that
would have an extended lifetime if the `else` branch was removed.
Default is `true`.
```
More information about the llvm-branch-commits
mailing list