add some comments

Author: lewing

src/Microsoft.DotNet.XHarness.TestRunners.Xunit/WasmXmlResultWriter.cs

@@ -30,8 +30,9 @@ private class ToBase64CharTransform : ICryptoTransform
     {
         private readonly ToBase64Transform _base64Transform = new ToBase64Transform();
 
-        public int InputBlockSize => _base64Transform.InputBlockSize;
-        public int OutputBlockSize => _base64Transform.OutputBlockSize * 2;
+        public int InputBlockSize => _base64Transform.InputBlockSize; // 3 bytes of input
+        public int OutputBlockSize => _base64Transform.OutputBlockSize * 2; // 4 bytes of base64 output * 2 for UTF-16 encoding
+
         public bool CanTransformMultipleBlocks => _base64Transform.CanTransformMultipleBlocks;
         public bool CanReuseTransform => _base64Transform.CanReuseTransform;
 
@@ -47,6 +48,7 @@ public int TransformBlock(
             int totalBytesWritten = 0;
             int inputProcessed = 0;
 
+            Debug.Assert(outputOffset % 2 == 0, $"{nameof(outputOffset)} must be a multiple 2");
             while (inputProcessed < inputCount)
             {
                 int bytesToProcess = Math.Min(InputBlockSize, inputCount - inputProcessed);
@@ -55,16 +57,48 @@ public int TransformBlock(
                 int base64OutputStart = outputOffset + totalBytesWritten + OutputBlockSize / 2;
                 int base64OutputLength = _base64Transform.OutputBlockSize;
 
-                // Apply Base64 transformation directly to the second half of the output buffer
+                // write Base64 transformation directly to the second half of the output buffer
                 int base64BytesWritten = _base64Transform.TransformBlock(
                     inputBuffer, inputOffset + inputProcessed, bytesToProcess,
                     outputBuffer, base64OutputStart);
 
-                var outputSpan = MemoryMarshal.Cast<byte, char>(outputBuffer.AsSpan(outputOffset + totalBytesWritten, OutputBlockSize));
+                /*
+                Input Buffer ("hi mom"):
+                +-----+-----+-----+-----+-----+-----+
+                | 'h' | 'i' | ' ' | 'm' | 'o' | 'm' |
+                +-----+-----+-----+-----+-----+-----+
+                |104  |105  | 32  |109  |111  |109  |
+                +-----+-----+-----+-----+-----+-----+
+
+                Base64 Encoding Process:
+                - 'hi ' -> 'aGkg'
+                - 'mom' -> 'bW9t'
+
+                Base64 Encoded Output:
+                |                   |base64Written      |                   | base64Written     |
+                +----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
+                | \0 | \0 | \0 | \0 |'a' |'G' |'k' |'g' | \0 | \0 | \0 | \0 |'b' |'W' |'9' |'t' |
+                +----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
+                |  0 |  0 |  0 |  0 | 97 | 71 |107 |103 |  0 |  0 |  0 |  0 | 98 | 87 | 57 |116 |
+                +----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
+
+                Expanded Output Buffer (UTF-16 Encoding):
+                | outputChars                           | outputChars                           |
+                +----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
+                | \0 |'a' | \0 |'G' | \0 |'k' | \0 |'g' | \0 |'b' | \0 |'W' | \0 |'9' | \0 |'t' |
+                +----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
+                | 0  | 97 | 0  | 71 | 0  |107 | 0  |103 | 0  | 98 | 0  | 87 | 0  | 57 | 0  |116 |
+                +----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
+
+                */
+
+                var base64Written = outputBuffer.AsSpan(base64OutputStart, base64BytesWritten);
+                var outputChars = MemoryMarshal.Cast<byte, char>(outputBuffer.AsSpan(outputOffset + totalBytesWritten, OutputBlockSize));
                 for (int i = 0; i < base64BytesWritten; i++)
                 {
-                    char base64Char = (char)outputBuffer[base64OutputStart + i];
-                    outputSpan[i] = base64Char;
+                    // Expand each acsii byte to a char write it in the same logical position
+                    // as a char in outputChars eventually filling the output buffer
+                    outputChars[i] = (char)base64Written[i];
                 }
 
                 inputProcessed += bytesToProcess;
@@ -84,9 +118,8 @@ public byte[] TransformFinalBlock(byte[] inputBuffer, int inputOffset, int input
             Span<char> outputSpan = MemoryMarshal.Cast<byte, char>(outputBuffer.AsSpan());
             for (int i = 0; i < base64Buffer.Length; i++)
             {
-                // Convert each byte to a char
-                char base64Char = (char)base64Buffer[i];
-                outputSpan[i] = base64Char;
+                // Convert each ascii byte to a char
+                outputSpan[i] = (char)base64Buffer[i]
             }
 
             return outputBuffer;
@@ -108,8 +141,12 @@ public static void WriteOnSingleLine(XElement assembliesElement)
         xmlWriter.Flush();
         cryptoStream.FlushFinalBlock();
 
+        // guranteed to succeed with the MemoryStream() constructor
         ms.TryGetBuffer(out var bytes);
-        var charData = MemoryMarshal.Cast<byte,char>(bytes);
+        // we went to a lot of trouble to put characters in the final buffer
+        // so that we can avoid a copy here and pass the span directly to the
+        // string interpolation logic.
+        Span<char> charData = MemoryMarshal.Cast<byte,char>(bytes);
 
         // Output the result
         Console.WriteLine($"STARTRESULTXML {charData.Length} {charData} ENDRESULTXML");