[llvm-branch-commits] [clang] [docs] Finish MyST migration for selected Clang docs (PR #214617)

[Reid Kleckner via llvm-branch-commits]

================
@@ -221,108 +203,104 @@ identified, disambiguated and characterised.
 
 As an example, consider the following structure:
 
-.. code-block:: c
-
-    struct A {
-        struct B {
-            int x;
-            int y;
-        } b;
-        struct C {
-            int a;
-            int b;
-        } c[2];
-        int z;
-    };
-    constexpr A a;
-
-On the target, ``&a`` and ``&a.b.x`` are equal. So are ``&a.c[0]`` and
-``&a.c[0].a``. In the interpreter, all these pointers must be
+```c
+struct A {
+    struct B {
+        int x;
+        int y;
+    } b;
+    struct C {
+        int a;
+        int b;
+    } c[2];
+    int z;
+};
+constexpr A a;
+```
+
+On the target, `&a` and `&a.b.x` are equal. So are `&a.c[0]` and
+`&a.c[0].a`. In the interpreter, all these pointers must be
 distinguished since they are all allowed to address a distinct range of
 memory.
 
 In the interpreter, the object would require 240 bytes of storage and
 would have its fields interleaved with metadata. The pointers which can
 be derived to the object are illustrated in the following diagram:
 
-::
-
-      0   16  32  40  56  64  80  96  112 120 136 144 160 176 184 200 208 224 240
-  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-  + B | D | D | x | D | y | D | D | D | a | D | b | D | D | a | D | b | D | z |
-  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
-      ^   ^   ^       ^       ^   ^   ^       ^       ^   ^       ^       ^
-      |   |   |       |       |   |   |   &a.c[0].b   |   |   &a.c[1].b   |
-      a   |&a.b.x  &a.b.y   &a.c  |&a.c[0].a          |&a.c[1].a          |
-        &a.b                   &a.c[0]            &a.c[1]               &a.z
-
-The ``Base`` offset of all pointers points to the start of a field or
-an array and is preceded by an inline descriptor (unless ``Base`` is
+```
+    0   16  32  40  56  64  80  96  112 120 136 144 160 176 184 200 208 224 240
++---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
++ B | D | D | x | D | y | D | D | D | a | D | b | D | D | a | D | b | D | z |
++---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
+    ^   ^   ^       ^       ^   ^   ^       ^       ^   ^       ^       ^
+    |   |   |       |       |   |   |   &a.c[0].b   |   |   &a.c[1].b   |
+    a   |&a.b.x  &a.b.y   &a.c  |&a.c[0].a          |&a.c[1].a          |
+      &a.b                   &a.c[0]            &a.c[1]               &a.z
+```
+
+The `Base` offset of all pointers points to the start of a field or
+an array and is preceded by an inline descriptor (unless `Base` is
 zero, pointing to the root). All the relevant attributes can be read
 from either the inline descriptor or the descriptor of the block.
 
-
-Array elements are identified by the ``Offset`` field of pointers,
+Array elements are identified by the `Offset` field of pointers,
 pointing to past the inline descriptors for composites and before
-the actual data in the case of primitive arrays. The ``Offset``
+the actual data in the case of primitive arrays. The `Offset`
 points to the offset where primitives can be read from. As an example,
-``a.c + 1`` would have the same base as ``a.c`` since it is an element
-of ``a.c``, but its offset would point to ``&a.c[1]``. The
+`a.c + 1` would have the same base as `a.c` since it is an element
+of `a.c`, but its offset would point to `&a.c[1]`. The
 array-to-pointer decay operation adjusts a pointer to an array (where
 the offset is equal to the base) to a pointer to the first element.
 
-TypeInfoPointer
-~~~~~~~~~~~~~~~
+#### TypeInfoPointer
 
-``TypeInfoPointer`` tracks two types: the type assigned to
-``std::type_info`` and the type which was passed to ``typeinfo``.
-It is part of the tagged union in ``Pointer``.
+`TypeInfoPointer` tracks two types: the type assigned to
+`std::type_info` and the type which was passed to `typeinfo`.
+It is part of the tagged union in `Pointer`.
 
+### Interpretation
 
-
-Interpretation
---------------
 After bytecode has been generated (or not, for expressions), the bytecode
-is then interpreted. The bytecode is stack-based and uses ``InterpStack``
+is then interpreted. The bytecode is stack-based and uses `InterpStack`
 to allocate memory for the produced values.
 
 Here is an example function:
 
-.. code-block:: c++
-
-    constexpr int add(int a, int b) {
-      return a + b;
-    }
-    static_assert(add(1, 2) == 3);
-
-Which generates the following bytecode (this can be produced via ``interp::Function::dump()``):
-
-::
-
-  add 0x7cb97f7e2000
-  [...]
-  0     GetParamSint32    0
-  16    GetParamSint32    1
-  32    AddSint32
-  40    RetSint32
-  48    NoRet
+```c++
+constexpr int add(int a, int b) {
+  return a + b;
+}
+static_assert(add(1, 2) == 3);
+```
+
+Which generates the following bytecode (this can be produced via `interp::Function::dump()`):
+
+```
+add 0x7cb97f7e2000
----------------
rnk wrote:

I left this code block alone, since I'm not sure what syntax it would use, but I did an audit of the rest of the fences in this change, and guessed the syntax and updated it. The changes fell into these categories:
- text -> mlir (CIR stuff)
- c++ -> hlsl (apparently there is an HLSL syntax we can use)
- text -> bnf (I didn't know that was a supported syntax either)
- text -> objdump

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