[clang] Add Documentation for Execution Results Handling in Clang-Repl (PR #65650)

[Vassil Vassilev via cfe-commits]

================
@@ -213,6 +213,411 @@ concept helps support advanced use cases such as template instantiations on dema
 automatic language interoperability. It also helps static languages such as C/C++ become
 apt for data science.
 
+Execution Results Handling in Clang-Repl
+========================================
+
+Execution Results Handling features discussed below help extend the Clang-Repl
+functionality by creating an interface between the execution results of a
+program and the compiled program.
+
+1. **Capture Execution Results**: This feature helps capture the execution results
+of a program and bring them back to the compiled program.
+
+2. **Dump Captured Execution Results**: This feature helps create a temporary dump
+for Value Printing/Automatic Printf, that is, to display the value and type of
+the captured data.
+
+
+1. Capture Execution Results
+============================
+
+In many cases, it is useful to bring back the program execution result to the
+compiled program. This result can be stored in an object of type **Value**.
+
+How Execution Results are captured (Value Synthesis):
+-----------------------------------------------------
+
+The synthesizer chooses which expression to synthesize, and then it replaces
+the original expression with the synthesized expression. Depending on the
+expression type, it may choose to save an object (``LastValue``) of type 'value'
+while allocating memory to it (``SetValueWithAlloc()``), or not (
+``SetValueNoAlloc()``).
+
+.. graphviz::
+    :name: valuesynthesis
+    :caption: Value Synthesis
+    :alt: Shows how an object of type 'Value' is synthesized
+    :align: center
+
+     digraph "valuesynthesis" {
+         rankdir="LR";
+         graph [fontname="Verdana", fontsize="12"];
+         node [fontname="Verdana", fontsize="12"];
+         edge [fontname="Sans", fontsize="9"];
+
+         start [label=" Create an Object \n 'Last Value' \n of type 'Value' ", shape="note", fontcolor=white, fillcolor="#3333ff", style=filled];
+         assign [label=" Assign the result \n to the 'LastValue' \n (based on respective \n Memory Allocation \n scenario) ", shape="box"]
+         print [label=" Pretty Print \n the Value Object ", shape="Msquare", fillcolor="yellow", style=filled];
+         start -> assign;
+         assign -> print;
+
+           subgraph SynthesizeExpression {
+             synth [label=" SynthesizeExpr() ", shape="note", fontcolor=white, fillcolor="#3333ff", style=filled];
+             mem [label=" New Memory \n Allocation? ", shape="diamond"];
+             withaloc [label=" SetValueWithAlloc() ", shape="box"];
+             noaloc [label=" SetValueNoAlloc() ", shape="box"];
+             right [label=" 1. RValue Structure \n (a temporary value)", shape="box"];
+             left2 [label=" 2. LValue Structure \n (a variable with \n an address)", shape="box"];
+             left3 [label=" 3. Built-In Type \n (int, float, etc.)", shape="box"];
+             output [label=" move to 'Assign' step ", shape="box"];
+
+             synth -> mem;
+             mem -> withaloc [label="Yes"];
+             mem -> noaloc [label="No"];
+             withaloc -> right;
+             noaloc -> left2;
+             noaloc -> left3;
+             right -> output;
+             left2 -> output;
+             left3 -> output;
+      }
+            output -> assign
+      }
+
+Where is the captured result stored?
+------------------------------------
+
+``LastValue`` holds the last result of the value printing. It is a class member
+because it can be accessed even after subsequent inputs.
+
+**Note:** If no value printing happens, then it is in an invalid state.
+
+Improving Efficiency and User Experience
+----------------------------------------
+
+The Value object is essentially used to create a mapping between an expression
+'type' and the allocated 'memory'. Built-in types (bool, char, int,
+float, double, etc.) are copyable. Their their memory allocation size is known
----------------
vgvassilev wrote:

```suggestion
float, double, etc.) are copyable. Their memory allocation size is known
```

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