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

[via llvm-branch-commits]

================
@@ -1,92 +1,91 @@
-.. title:: clang-tidy - readability-magic-numbers
+```{title} clang-tidy - readability-magic-numbers
+```
 
-readability-magic-numbers
-=========================
+# readability-magic-numbers
 
 Detects magic numbers, integer or floating point literals that are embedded in
 code and not introduced via constants or symbols.
 
 Many coding guidelines advise replacing the magic values with symbolic
 constants to improve readability. Here are a few references:
 
-   * `Rule ES.45: Avoid "magic constants"; use symbolic constants in C++ Core Guidelines <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#res-magic>`_
-   * Item 17 in "C++ Coding Standards: 101 Rules, Guidelines and Best
-     Practices" by Herb Sutter and Andrei Alexandrescu
-   * Chapter 17 in "Clean Code - A handbook of agile software craftsmanship."
-     by Robert C. Martin
-   * Rule 20701 in "TRAIN REAL TIME DATA PROTOCOL Coding Rules" by Armin-Hagen
-     Weiss, Bombardier
-   * http://wiki.c2.com/?MagicNumber
-
+- [Rule ES.45: Avoid "magic constants"; use symbolic constants in C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#res-magic)
+- Item 17 in "C++ Coding Standards: 101 Rules, Guidelines and Best
+  Practices" by Herb Sutter and Andrei Alexandrescu
+- Chapter 17 in "Clean Code - A handbook of agile software craftsmanship."
+  by Robert C. Martin
+- Rule 20701 in "TRAIN REAL TIME DATA PROTOCOL Coding Rules" by Armin-Hagen
+  Weiss, Bombardier
+- <http://wiki.c2.com/?MagicNumber>
 
 Examples of magic values:
 
-.. code-block:: c++
-
-   template<typename T, size_t N>
-   struct CustomType {
-      T arr[N];
-   };
+```c++
+template<typename T, size_t N>
+struct CustomType {
+   T arr[N];
+};
 
-   struct OtherType {
-      CustomType<int, 30> container;
-   }
-   CustomType<int, 30> values;
+struct OtherType {
+   CustomType<int, 30> container;
+}
+CustomType<int, 30> values;
 
-   double circleArea = 3.1415926535 * radius * radius;
+double circleArea = 3.1415926535 * radius * radius;
 
-   double totalCharge = 1.08 * itemPrice;
+double totalCharge = 1.08 * itemPrice;
 
-   int getAnswer() {
-      return -3; // FILENOTFOUND
-   }
+int getAnswer() {
+   return -3; // FILENOTFOUND
+}
 
-   for (int mm = 1; mm <= 12; ++mm) {
-      std::cout << month[mm] << '\n';
-   }
+for (int mm = 1; mm <= 12; ++mm) {
+   std::cout << month[mm] << '\n';
+}
+```
 
 Example with magic values refactored:
 
-.. code-block:: c++
-
-   template<typename T, size_t N>
-   struct CustomType {
-      T arr[N];
-   };
+```c++
+template<typename T, size_t N>
+struct CustomType {
+   T arr[N];
+};
 
-   const size_t NUMBER_OF_ELEMENTS = 30;
-   using containerType = CustomType<int, NUMBER_OF_ELEMENTS>;
+const size_t NUMBER_OF_ELEMENTS = 30;
+using containerType = CustomType<int, NUMBER_OF_ELEMENTS>;
 
-   struct OtherType {
-      containerType container;
-   }
-   containerType values;
+struct OtherType {
+   containerType container;
+}
+containerType values;
 
-   double circleArea = M_PI * radius * radius;
+double circleArea = M_PI * radius * radius;
 
-   const double TAX_RATE = 0.08;  // or make it variable and read from a file
+const double TAX_RATE = 0.08;  // or make it variable and read from a file
 
-   double totalCharge = (1.0 + TAX_RATE) * itemPrice;
+double totalCharge = (1.0 + TAX_RATE) * itemPrice;
 
-   int getAnswer() {
-      return E_FILE_NOT_FOUND;
-   }
+int getAnswer() {
+   return E_FILE_NOT_FOUND;
+}
 
-   for (int mm = 1; mm <= MONTHS_IN_A_YEAR; ++mm) {
-      std::cout << month[mm] << '\n';
-   }
+for (int mm = 1; mm <= MONTHS_IN_A_YEAR; ++mm) {
+   std::cout << month[mm] << '\n';
+}
+```
 
 For integral literals by default only `0` and `1` (and `-1`) integer values
 are accepted without a warning. This can be overridden with the
-:option:`IgnoredIntegerValues` option. Negative values are accepted if their
-absolute value is present in the :option:`IgnoredIntegerValues` list.
+{option}`IgnoredIntegerValues` option. Negative values are accepted if their
+absolute value is present in the {option}`IgnoredIntegerValues` list.
 
 As a special case for integral values, all powers of two can be accepted
-without warning by enabling the :option:`IgnorePowersOf2IntegerValues` option.
+without warning by enabling the {option}`IgnorePowersOf2IntegerValues` option.
 
 For floating point literals by default the `0.0` floating point value is
 accepted without a warning. The set of ignored floating point literals can
-be configured using the :option:`IgnoredFloatingPointValues` option.
+be configured using the {option}`IgnoredFloatingPointValues` option.
----------------
EugeneZelenko wrote:

```suggestion
be configured using the {option}`IgnoredFloatingPointValues`.
```

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