[llvm-branch-commits] [clang-tools-extra] [clang-tidy][docs] Rewrite readability check docs to Markdown [1/5] (PR #221447)

[via llvm-branch-commits]

llvmorg-github-actions[bot] wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang-tidy

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 first 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 32.23 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/221447.diff


10 Files Affected:

- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/ambiguous-smartptr-reset-call.md (+46-44) 
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/avoid-return-with-void-value.md (+31-33) 
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/avoid-unconditional-preprocessor-if.md (+16-16) 
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/braces-around-statements.md (+23-24) 
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/const-return-type.md (+20-22) 
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/container-contains.md (+23-25) 
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/container-size-empty.md (+25-27) 
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/duplicate-include.md (+28-29) 
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md (+66-71) 
- (modified) clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.md (+94-97) 


``````````diff
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-incl...
[truncated]

``````````

</details>


https://github.com/llvm/llvm-project/pull/221447