Added comments to unit tests

Author: Sergio0694

UnitTests/UnitTests.HighPerformance.Shared/Buffers/Test_ArrayPoolBufferWriter{T}.cs

@@ -3,7 +3,6 @@
 // See the LICENSE file in the project root for more information.
 
 using System;
-using System.Buffers;
 using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Linq;
@@ -150,28 +149,43 @@ public void Test_ArrayPoolBufferWriterOfT_MultipleDispose()
         [TestMethod]
         public void Test_ArrayPoolBufferWriterOfT_AsStream()
         {
-            var writer = new ArrayPoolBufferWriter<byte>();
-
-            Span<byte> data = Guid.NewGuid().ToByteArray();
+            const int GuidSize = 16;
 
-            data.CopyTo(writer.GetSpan(data.Length));
+            var writer = new ArrayPoolBufferWriter<byte>();
+            var guid = Guid.NewGuid();
 
-            writer.Advance(data.Length);
+            // Here we first get a stream with the extension targeting ArrayPoolBufferWriter<T>.
+            // This will wrap it into a custom internal stream type and produce a write-only
+            // stream that essentially mirrors the IBufferWriter<T> functionality as a stream.
+            using (Stream writeStream = writer.AsStream())
+            {
+                writeStream.Write(guid);
+            }
 
-            Assert.AreEqual(writer.WrittenCount, data.Length);
+            Assert.AreEqual(writer.WrittenCount, GuidSize);
 
-            Stream stream = ((IMemoryOwner<byte>)writer).AsStream();
+            // Here we get a readable stream instead, and read from it to ensure
+            // the previous data was written correctly from the writeable stream.
+            using (Stream stream = writer.WrittenMemory.AsStream())
+            {
+                Assert.AreEqual(stream.Length, GuidSize);
 
-            Assert.AreEqual(stream.Length, data.Length);
+                byte[] result = new byte[GuidSize];
 
-            byte[] result = new byte[16];
+                stream.Read(result, 0, result.Length);
 
-            stream.Read(result, 0, result.Length);
+                // Read the guid data and ensure it matches our initial guid
+                Assert.IsTrue(new Guid(result).Equals(guid));
+            }
 
-            Assert.IsTrue(data.SequenceEqual(result));
+            // Do a dummy write just to ensure the writer isn't disposed here.
+            // This is because we got a stream from a memory, not a memory owner.
+            writer.Write((byte)42);
+            writer.Advance(1);
 
-            stream.Dispose();
+            writer.Dispose();
 
+            // Now check that the writer is actually disposed instead
             Assert.ThrowsException<ObjectDisposedException>(() => writer.Capacity);
         }
     }

UnitTests/UnitTests.HighPerformance.Shared/Streams/Test_IBufferWriterStream.cs

@@ -22,6 +22,8 @@ public void Test_IBufferWriterStream_Lifecycle()
         {
             ArrayPoolBufferWriter<byte> writer = new ArrayPoolBufferWriter<byte>();
 
+            // Get a stream from a buffer writer aand validate that it can only be written to.
+            // This is to mirror the same functionality as the IBufferWriter<T> interface.
             Stream stream = ((IBufferWriter<byte>)writer).AsStream();
 
             Assert.IsFalse(stream.CanRead);
@@ -31,6 +33,7 @@ public void Test_IBufferWriterStream_Lifecycle()
             Assert.ThrowsException<NotSupportedException>(() => stream.Length);
             Assert.ThrowsException<NotSupportedException>(() => stream.Position);
 
+            // Dispose the stream and check that no operation is now allowed
             stream.Dispose();
 
             Assert.IsFalse(stream.CanRead);
@@ -49,11 +52,14 @@ public void Test_IBufferWriterStream_Write_Array()
 
             byte[] data = Test_MemoryStream.CreateRandomData(64);
 
+            // Write random data to the stream wrapping the buffer writer, and validate
+            // that the state of the writer is consistent, and the written content matches.
             stream.Write(data, 0, data.Length);
 
             Assert.AreEqual(writer.WrittenCount, data.Length);
             Assert.IsTrue(writer.WrittenSpan.SequenceEqual(data));
 
+            // A few tests with invalid inputs (null buffers, invalid indices, etc.)
             Assert.ThrowsException<ArgumentNullException>(() => stream.Write(null, 0, 10));
             Assert.ThrowsException<ArgumentOutOfRangeException>(() => stream.Write(data, -1, 10));
             Assert.ThrowsException<ArgumentException>(() => stream.Write(data, 200, 10));
@@ -74,6 +80,7 @@ public async Task Test_IBufferWriterStream_WriteAsync_Array()
 
             byte[] data = Test_MemoryStream.CreateRandomData(64);
 
+            // Same test as above, but using an asynchronous write instead
             await stream.WriteAsync(data, 0, data.Length);
 
             Assert.AreEqual(writer.WrittenCount, data.Length);
@@ -102,11 +109,15 @@ public void Test_IBufferWriterStream_WriteByte()
 
             foreach (var item in data.Enumerate())
             {
+                // Since we're enumerating, we can also double check the current written count
+                // at each iteration, to ensure the writes are done correctly every time.
                 Assert.AreEqual(writer.WrittenCount, item.Index);
 
+                // Write a number of bytes one by one to test this API as well
                 stream.WriteByte(item.Value);
             }
 
+            // Validate the final written length and actual data
             Assert.AreEqual(writer.WrittenCount, data.Length);
             Assert.IsTrue(data.SequenceEqual(writer.WrittenSpan));
 
@@ -140,6 +151,7 @@ public async Task Test_IBufferWriterStream_WriteAsync_Memory()
 
             Memory<byte> data = Test_MemoryStream.CreateRandomData(64);
 
+            // Same as the other asynchronous test above, but writing from a Memory<T>
             await stream.WriteAsync(data);
 
             Assert.AreEqual(writer.WrittenCount, data.Length);