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

[via llvm-branch-commits]

================
@@ -1,166 +1,168 @@
-.. title:: clang-tidy - readability-function-cognitive-complexity
+```{title} clang-tidy - readability-function-cognitive-complexity
+```
 
-readability-function-cognitive-complexity
-=========================================
+# readability-function-cognitive-complexity
 
 Checks function Cognitive Complexity metric.
 
-The metric is implemented as per the `COGNITIVE COMPLEXITY by SonarSource
-<https://www.sonarsource.com/docs/CognitiveComplexity.pdf>`_ specification
+The metric is implemented as per the [COGNITIVE COMPLEXITY by SonarSource](https://www.sonarsource.com/docs/CognitiveComplexity.pdf) specification
 version 1.2 (19 April 2017).
 
-Options
--------
+## Options
 
-.. option:: Threshold
+```{option} Threshold
+Flag functions with Cognitive Complexity exceeding this number.
+Default is `25`.
+```
 
-   Flag functions with Cognitive Complexity exceeding this number.
-   The default is `25`.
+```{option} DescribeBasicIncrements
+When `true`, for each function exceeding the complexity threshold
+the check will issue additional diagnostics on every piece of code (loop,
+`if` statement, etc.) which contributes to that complexity. See also the
+examples below. Default is `true`.
+```
 
-.. option:: DescribeBasicIncrements
+```{option} IgnoreMacros
+When `true`, the check will ignore code inside macros. Note that
+any macro arguments are ignored, even if they should count to the complexity.
+As this might change in the future, this option isn't guaranteed to be
+forward-compatible. Default is `false`.
+```
 
-   If set to `true`, then for each function exceeding the complexity threshold
-   the check will issue additional diagnostics on every piece of code (loop,
-   `if` statement, etc.) which contributes to that complexity. See also the
-   examples below. Default is `true`.
-
-.. option:: IgnoreMacros
-
-   If set to `true`, the check will ignore code inside macros. Note, that also
-   any macro arguments are ignored, even if they should count to the complexity.
-   As this might change in the future, this option isn't guaranteed to be
-   forward-compatible. Default is `false`.
-
-Building blocks
----------------
+## Building blocks
 
 There are three basic building blocks of a Cognitive Complexity metric:
 
-Increment
-^^^^^^^^^
+### Increment
 
 The following structures increase the function's Cognitive Complexity metric
 (by `1`):
 
-* Conditional operators:
+- Conditional operators:
+
+  - `if()`
+  - `else if()`
+  - `else`
+  - `cond ? true : false`
+
+- `switch()`
+
+- Loops:
 
-   - ``if()``
-   - ``else if()``
-   - ``else``
-   - ``cond ? true : false``
+  - `for()`
+  - C++11 range-based `for()`
+  - `while()`
+  - `do while()`
 
-* ``switch()``
-* Loops:
+- `catch ()`
 
-   - ``for()``
-   - C++11 range-based ``for()``
-   - ``while()``
-   - ``do while()``
+- `goto LABEL`, `goto *(&&LABEL))`,
 
-* ``catch ()``
-* ``goto LABEL``, ``goto *(&&LABEL))``,
-* sequences of binary logical operators:
+- sequences of binary logical operators:
 
-   - ``boolean1 || boolean2``
-   - ``boolean1 && boolean2``
+  - `boolean1 || boolean2`
+  - `boolean1 && boolean2`
 
-Nesting level
-^^^^^^^^^^^^^
+### Nesting level
 
 While by itself the nesting level does not change the function's Cognitive
 Complexity metric, it is tracked, and is used by the next, third building
 block. The following structures increase the nesting level (by `1`):
 
-* Conditional operators:
+- Conditional operators:
 
-   - ``if()``
-   - ``else if()``
-   - ``else``
-   - ``cond ? true : false``
+  - `if()`
+  - `else if()`
+  - `else`
+  - `cond ? true : false`
 
-* ``switch()``
-* Loops:
+- `switch()`
 
-   - ``for()``
-   - C++11 range-based ``for()``
-   - ``while()``
-   - ``do while()``
+- Loops:
 
-* ``catch ()``
-* Nested functions:
+  - `for()`
+  - C++11 range-based `for()`
+  - `while()`
+  - `do while()`
 
-   - C++11 Lambda
-   - Nested ``class``
-   - Nested ``struct``
-* GNU statement expression
-* Apple Block Declaration
+- `catch ()`
 
-Nesting increment
-^^^^^^^^^^^^^^^^^
+- Nested functions:
 
-This is where the previous basic building block, `Nesting level`_, matters.
-The following structures increase the function's Cognitive Complexity metric by
-the current `Nesting level`_:
+  - C++11 Lambda
+  - Nested `class`
+  - Nested `struct`
 
-* Conditional operators:
+- GNU statement expression
 
-   - ``if()``
-   - ``cond ? true : false``
+- Apple Block Declaration
 
-* ``switch()``
-* Loops:
+### Nesting increment
 
-   - ``for()``
-   - C++11 range-based ``for()``
-   - ``while()``
-   - ``do while()``
+This is where the previous basic building block,
+[Nesting level](#nesting-level), matters.
+The following structures increase the function's Cognitive Complexity metric by
+the current [Nesting level](#nesting-level):
 
-* ``catch ()``
+- Conditional operators:
 
-Examples
---------
+  - `if()`
+  - `cond ? true : false`
 
-The simplest case. This function has Cognitive Complexity of `0`.
+- `switch()`
 
-.. code-block:: c++
+- Loops:
 
-  void function0() {}
+  - `for()`
+  - C++11 range-based `for()`
+  - `while()`
+  - `do while()`
 
-Slightly better example. This function has Cognitive Complexity of `1`.
+- `catch ()`
 
-.. code-block:: c++
+## Examples
 
-  int function1(bool var) {
-    if(var) // +1, nesting level +1
-      return 42;
-    return 0;
-  }
+The simplest case. This function has Cognitive Complexity of `0`.
 
-Full example. This function has Cognitive Complexity of `3`.
+```c++
+void function0() {}
+```
+
+Slightly better example. This function has Cognitive Complexity of `1`.
 
-.. code-block:: c++
+```c++
+int function1(bool var) {
+  if(var) // +1, nesting level +1
+    return 42;
+  return 0;
+}
+```
 
-  int function3(bool var1, bool var2) {
-    if(var1) { // +1, nesting level +1
-      if(var2)  // +2 (1 + current nesting level of 1), nesting level +1
-        return 42;
-    }
+Full example. This function has Cognitive Complexity of `3`.
 
-    return 0;
+```c++
+int function3(bool var1, bool var2) {
+  if(var1) { // +1, nesting level +1
+    if(var2)  // +2 (1 + current nesting level of 1), nesting level +1
+      return 42;
   }
 
-In the last example, the check will flag `function3` if the option Threshold is
-set to `2` or smaller. If the option DescribeBasicIncrements is set to `true`,
+  return 0;
+}
+```
+
+In the last example, the check will flag `function3` if the
+{option}`Threshold` option is set to `2` or smaller. If the
+{option}`DescribeBasicIncrements` option is set to `true`,
----------------
EugeneZelenko wrote:

```suggestion
{option}`Threshold` is set to `2` or smaller. If the
{option}`DescribeBasicIncrements` is set to `true`,
```

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