update README.md, add document comments

PooledStream.sln

@@ -1,13 +1,18 @@
-Microsoft Visual Studio Solution File, Format Version 12.0
-# Visual Studio Version 16
-VisualStudioVersion = 16.0
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.32002.185
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "PooledStream.Benchmark", "PooledStream.Benchmark\PooledStream.Benchmark.csproj", "{41130469-5601-4C78-87DC-14574AD1EB0F}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "PooledStream.Test", "PooledStream.Test\PooledStream.Test.csproj", "{DA3F4EB2-D0F8-49C3-8A34-C86412EFC151}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "PooledStream", "PooledStream\PooledStream.csproj", "{3C446344-2FF5-45F9-9010-3227F715B8A9}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{180A5C83-F82B-40F0-BCAF-F240679667EC}"
+	ProjectSection(SolutionItems) = preProject
+		README.md = README.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|AnyCPU = Debug|AnyCPU
@@ -27,4 +32,10 @@ Global
 		{3C446344-2FF5-45F9-9010-3227F715B8A9}.Release|AnyCPU.ActiveCfg = Debug|Any CPU
 		{3C446344-2FF5-45F9-9010-3227F715B8A9}.Release|AnyCPU.Build.0 = Debug|Any CPU
 	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {F11B0785-81AF-4F25-9079-8A1432151A79}
+	EndGlobalSection
 EndGlobal

PooledStream/PooledBufferWriter.cs

@@ -22,31 +22,55 @@ void Reallocate(int sizeHint)
             }
             _currentBuffer = nar;
         }
+        /// <summary>
+        /// use shared instance and preallocatedSize = 1024
+        /// </summary>
         public PooledMemoryBufferWriter() : this(ArrayPool<T>.Shared)
         {
 
         }
+        /// <summary>
+        /// use shared instance, use preallocateSize as reserved buffer length
+        /// </summary>
+        /// <param name="preallocateSize">initial reserved buffer size</param>
         public PooledMemoryBufferWriter(int preallocateSize) : this(ArrayPool<T>.Shared, preallocateSize)
         {
 
         }
+        /// <summary>
+        /// use pool for memory pool
+        /// </summary>
+        /// <param name="pool">memory pool</param>
         public PooledMemoryBufferWriter(ArrayPool<T> pool) : this(pool, DefaultSize)
         {
         }
+        /// <summary>
+        /// </summary>
+        /// <param name="pool">memory pool</param>
+        /// <param name="preallocateSize">initial reserved buffer size</param>
         public PooledMemoryBufferWriter(ArrayPool<T> pool, int preallocateSize)
         {
+            if(pool == null)
+            {
+                throw new ArgumentNullException(nameof(pool));
+            }
+            if(preallocateSize < 0)
+            {
+                throw new ArgumentOutOfRangeException(nameof(preallocateSize), "size must be greater than 0");
+            }
             _Pool = pool;
             _currentBuffer = null;
             _Position = 0;
             _Length = 0;
             Reallocate(preallocateSize);
         }
+        /// <inheritdoc/>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public void Advance(int count)
         {
             if (_Position + count > _currentBuffer.Length)
             {
-                throw new IndexOutOfRangeException("advance too many(" + count.ToString() + ")");
+                throw new ArgumentOutOfRangeException("advance too many(" + count.ToString() + ")");
             }
             _Position += count;
             if (_Length < _Position)
@@ -55,6 +79,7 @@ public void Advance(int count)
             }
         }
 
+        /// <summary>return buffer to pool and reset buffer status</summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public void Dispose()
         {
@@ -67,9 +92,14 @@ public void Dispose()
             }
         }
 
+        /// <inheritdoc/>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public Memory<T> GetMemory(int sizeHint = 0)
         {
+            if (sizeHint < 0)
+            {
+                throw new ArgumentOutOfRangeException("sizeHint", "size must be greater than 0");
+            }
             if (sizeHint == 0)
             {
                 sizeHint = DefaultSize;
@@ -80,10 +110,14 @@ public Memory<T> GetMemory(int sizeHint = 0)
             }
             return _currentBuffer.AsMemory(_Position, sizeHint);
         }
-
+        /// <inheritdoc/>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public Span<T> GetSpan(int sizeHint = 0)
         {
+            if (sizeHint < 0)
+            {
+                throw new ArgumentOutOfRangeException("sizeHint", "size must be greater than 0");
+            }
             if (sizeHint == 0)
             {
                 sizeHint = DefaultSize;
@@ -94,23 +128,37 @@ public Span<T> GetSpan(int sizeHint = 0)
             }
             return _currentBuffer.AsSpan(_Position, sizeHint);
         }
+        /// <summary>expose current buffer as Span</summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public ReadOnlySpan<T> ToSpanUnsafe()
         {
             return _currentBuffer.AsSpan(0, _Length);
         }
+        /// <summary>expose current buffer as Memory</summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public ReadOnlyMemory<T> ToMemoryUnsafe()
         {
             return _currentBuffer.AsMemory(0, _Length);
         }
+        /// <summary>reset buffer status, buffer will be reallocated</summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Reset(int preallocateSize = DefaultSize)
+        public void Reset(int preallocateSize)
         {
+            if(preallocateSize < 0)
+            {
+                throw new ArgumentOutOfRangeException("preallocateSize", "size must be greater than 0");
+            }
             _Pool.Return(_currentBuffer);
             _currentBuffer = _Pool.Rent(preallocateSize);
             _Length = 0;
             _Position = 0;
         }
+        /// <summary>reset buffer status, buffer will be reused</summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void Reset()
+        {
+            _Length = 0;
+            _Position = 0;
+        }
     }
 }

PooledStream/PooledStream.csproj

@@ -4,13 +4,13 @@
     <TargetFrameworks>netstandard2.1;netstandard1.1</TargetFrameworks>
     <!-- <TargetFramework>netstandard2.1</TargetFramework> -->
     <PackageId>PooledStream</PackageId>
-    <PackageVersion>0.2.1.2</PackageVersion>
+    <PackageVersion>0.3.0</PackageVersion>
     <Authors>itn3000</Authors>
     <Description>Efficient MemoryStream powered by System.Buffers.ArrayPool</Description>
     <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
-    <PackageReleaseNotes>add netstandard2.1 to TargetFramework</PackageReleaseNotes>
+    <PackageReleaseNotes>add PooledMemoryBufferWriter</PackageReleaseNotes>
     <Copyright>Copyright(c) 2017 itn3000. All rights reserved</Copyright>
-    <PackageTags>MemoryStream</PackageTags>
+    <PackageTags>MemoryStream;ArrayPool</PackageTags>
     <PackageProjectUrl>https://github.com/itn3000/PooledStream/</PackageProjectUrl>
     <RepositoryUrl>https://github.com/itn3000/PooledStream/</RepositoryUrl>
     <PackageLicenseFile>LICENSE.md</PackageLicenseFile>