[llvm-branch-commits] [clang-tools-extra] [clang-tidy][docs] Rewrite modernize check docs to Markdown [1/4] (PR #232207)

[via llvm-branch-commits]

================
@@ -25,264 +23,260 @@ in the transformation due to the increased risk of changing semantics.
 Transformations for these loops are marked as `risky`, and thus will only
 be converted if the minimum required confidence level is set to `risky`.
 
-.. code-block:: c++
+```c++
+int arr[10][20];
+int l = 5;
 
-  int arr[10][20];
-  int l = 5;
+for (int j = 0; j < 20; ++j)
+  int k = arr[l][j] + l; // using l outside arr[l] is considered risky
 
-  for (int j = 0; j < 20; ++j)
-    int k = arr[l][j] + l; // using l outside arr[l] is considered risky
-
-  for (int i = 0; i < obj.getVector().size(); ++i)
-    obj.foo(10); // using 'obj' is considered risky
+for (int i = 0; i < obj.getVector().size(); ++i)
+  obj.foo(10); // using 'obj' is considered risky
+```
 
 See
-:ref:`Range-based loops evaluate end() only once<IncorrectRiskyTransformation>`
+{ref}`Range-based loops evaluate end() only once<IncorrectRiskyTransformation>`
 for an example of an incorrect transformation when the minimum required confidence
 level is set to `risky`.
 
-reasonable (Default)
-^^^^^^^^^^^^^^^^^^^^
+### reasonable (Default)
 
-If a loop calls ``.end()`` or ``.size()`` after each iteration, the
+If a loop calls `.end()` or `.size()` after each iteration, the
 transformation for that loop is marked as `reasonable`, and thus will
 be converted if the required confidence level is set to `reasonable`
 (default) or lower.
 
-.. code-block:: c++
-
-  // using size() is considered reasonable
-  for (int i = 0; i < container.size(); ++i)
-    cout << container[i];
+```c++
+// using size() is considered reasonable
+for (int i = 0; i < container.size(); ++i)
+  cout << container[i];
+```
 
-safe
-^^^^
+### safe
 
 Any other loops that do not match the above criteria to be marked as
 `risky` or `reasonable` are marked `safe`, and thus will be converted
 if the required confidence level is set to `safe` or lower.
 
-.. code-block:: c++
-
-  int arr[] = {1,2,3};
+```c++
+int arr[] = {1,2,3};
 
-  for (int i = 0; i < 3; ++i)
-    cout << arr[i];
+for (int i = 0; i < 3; ++i)
+  cout << arr[i];
+```
 
-Example
--------
+## Example
 
 Original:
 
-.. code-block:: c++
+```c++
+const int N = 5;
+int arr[] = {1,2,3,4,5};
+vector<int> v;
+v.push_back(1);
+v.push_back(2);
+v.push_back(3);
 
-  const int N = 5;
-  int arr[] = {1,2,3,4,5};
-  vector<int> v;
-  v.push_back(1);
-  v.push_back(2);
-  v.push_back(3);
+// safe conversion
+for (int i = 0; i < N; ++i)
+  cout << arr[i];
 
-  // safe conversion
-  for (int i = 0; i < N; ++i)
-    cout << arr[i];
+// reasonable conversion
+for (vector<int>::iterator it = v.begin(); it != v.end(); ++it)
+  cout << *it;
 
-  // reasonable conversion
-  for (vector<int>::iterator it = v.begin(); it != v.end(); ++it)
-    cout << *it;
+// reasonable conversion
+for (vector<int>::iterator it = begin(v); it != end(v); ++it)
+  cout << *it;
 
-  // reasonable conversion
-  for (vector<int>::iterator it = begin(v); it != end(v); ++it)
-    cout << *it;
+// reasonable conversion
+for (vector<int>::iterator it = std::begin(v); it != std::end(v); ++it)
+  cout << *it;
 
-  // reasonable conversion
-  for (vector<int>::iterator it = std::begin(v); it != std::end(v); ++it)
-    cout << *it;
+// reasonable conversion
+for (int i = 0; i < v.size(); ++i)
+  cout << v[i];
 
-  // reasonable conversion
-  for (int i = 0; i < v.size(); ++i)
-    cout << v[i];
-
-  // reasonable conversion
-  for (int i = 0; i < size(v); ++i)
-    cout << v[i];
+// reasonable conversion
+for (int i = 0; i < size(v); ++i)
+  cout << v[i];
+```
 
 After applying the check with minimum confidence level set to
 `reasonable` (default):
 
-.. code-block:: c++
-
-  const int N = 5;
-  int arr[] = {1,2,3,4,5};
-  vector<int> v;
-  v.push_back(1);
-  v.push_back(2);
-  v.push_back(3);
+```c++
+const int N = 5;
+int arr[] = {1,2,3,4,5};
+vector<int> v;
+v.push_back(1);
+v.push_back(2);
+v.push_back(3);
 
-  // safe conversion
-  for (auto & elem : arr)
-    cout << elem;
+// safe conversion
+for (auto & elem : arr)
+  cout << elem;
 
-  // reasonable conversion
-  for (auto & elem : v)
-    cout << elem;
+// reasonable conversion
+for (auto & elem : v)
+  cout << elem;
 
-  // reasonable conversion
-  for (auto & elem : v)
-    cout << elem;
+// reasonable conversion
+for (auto & elem : v)
+  cout << elem;
+```
 
-Reverse Iterator Support
-------------------------
+## Reverse Iterator Support
 
 The converter is also capable of transforming iterator loops which use
-``rbegin`` and ``rend`` for looping backwards over a container. Out of the box
-this will automatically happen in C++20 mode using the ``ranges`` library,
+`rbegin` and `rend` for looping backwards over a container. Out of the box
+this will automatically happen in C++20 mode using the `ranges` library,
 however the check can be configured to work without C++20 by specifying a
 function to reverse a range and optionally the header file where that function
 lives.
 
-Options
--------
+## Options
 
-.. option:: UseCxx20ReverseRanges
+(modernize-loop-convert-use-cxx20-reverse-ranges)=
 
-   When set to true convert loops when in C++20 or later mode using
-   ``std::views::reverse``.
-   Default value is `true`.
+```{option} UseCxx20ReverseRanges
+When set to true convert loops when in C++20 or later mode using
+`std::views::reverse`.
+Default is `true`.
+```
 
-.. option:: MakeReverseRangeFunction
+(modernize-loop-convert-make-reverse-range-function)=
 
-   Specify the function used to reverse an iterator pair, the function should
-   accept a class with ``rbegin`` and ``rend`` methods and return a
-   class with ``begin`` and ``end`` methods that call the ``rbegin`` and
-   ``rend`` methods respectively. Common examples are ``std::views::reverse``
-   and ``llvm::reverse``.
-   Default value is an empty string.
+```{option} MakeReverseRangeFunction
+Specify the function used to reverse an iterator pair, the function should
+accept a class with `rbegin` and `rend` methods and return a
+class with `begin` and `end` methods that call the `rbegin` and
+`rend` methods respectively. Common examples are `std::views::reverse`
+and `llvm::reverse`.
+Default is an empty string.
+```
 
-.. option:: MakeReverseRangeHeader
+(modernize-loop-convert-make-reverse-range-header)=
 
-   Specifies the header file where :option:`MakeReverseRangeFunction` is
-   declared. For the previous examples this option would be set to
-   ``range/v3/view/reverse.hpp`` and ``llvm/ADT/STLExtras.h`` respectively.
-   If this is an empty string and :option:`MakeReverseRangeFunction` is set,
-   the check will proceed on the assumption that the function is already
-   available in the translation unit.
-   This can be wrapped in angle brackets to signify to add the include as a
-   system include.
-   Default value is an empty string.
+```{option} MakeReverseRangeHeader
+Specifies the header file where [`MakeReverseRangeFunction`](#modernize-loop-convert-make-reverse-range-function) is
----------------
EugeneZelenko wrote:

`{option}`?

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