updated comment for benchmarks

Author: petesramek

benchmarks/PolylineAlgorithm.Benchmarks/PolylineBenchmark.cs

@@ -11,11 +11,14 @@ namespace PolylineAlgorithm.Benchmarks;
 using PolylineAlgorithm.Utility;
 
 /// <summary>
-/// Benchmarks for the <see cref="PolylineValue"/> struct.
+/// Benchmarks for <see cref="Polyline"/>.
 /// </summary>
 public class PolylineBenchmark {
     private static readonly Consumer _consumer = new();
 
+    /// <summary>
+    /// Number of coordinates for benchmarks. Set by BenchmarkDotNet.
+    /// </summary>
     [Params(1, 100, 1_000)]
     public int CoordinatesCount;
 
@@ -45,6 +48,11 @@ public class PolylineBenchmark {
     /// </summary>
     public Polyline PolylineNotEqualValue { get; private set; }
 
+    /// <summary>
+    /// Gets the destination array used for benchmarking the <see cref="Polyline.CopyTo(char[])"/> method.
+    /// This array is initialized in <see cref="SetupData"/> to match the length of the encoded polyline,
+    /// and is used as the target buffer for copying polyline data during benchmark runs.
+    /// </summary>
     public char[] CopyToDestination { get; private set; }
 
 #pragma warning restore CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring as nullable.
@@ -65,7 +73,7 @@ public void SetupData() {
     }
 
     /// <summary>
-    /// Benchmarks the encoding of a list of coordinates into a polyline.
+    /// Benchmark: create polyline from string.
     /// </summary>
     /// <returns>The encoded polyline.</returns>
     [Benchmark]
@@ -77,7 +85,7 @@ public void Polyline_FromString() {
     }
 
     /// <summary>
-    /// Benchmarks the encoding of an enumeration of coordinates into a polyline.
+    /// Benchmark: create polyline from char array.
     /// </summary>
     /// <returns>The encoded polyline.</returns>
     [Benchmark]
@@ -89,7 +97,7 @@ public void Polyline_FromCharArray() {
     }
 
     /// <summary>
-    /// Benchmarks the encoding of an enumeration of coordinates into a polyline.
+    /// Benchmark: create polyline from memory.
     /// </summary>
     /// <returns>The encoded polyline.</returns>
     [Benchmark]
@@ -101,7 +109,7 @@ public void Polyline_FromMemory() {
     }
 
     /// <summary>
-    /// Benchmarks the encoding of an enumeration of coordinates into a polyline.
+    /// Benchmark: convert polyline to string.
     /// </summary>
     /// <returns>The encoded polyline.</returns>
     [Benchmark]
@@ -114,7 +122,7 @@ public void Polyline_ToString() {
 
 
     /// <summary>
-    /// Benchmarks the encoding of an enumeration of coordinates into a polyline.
+    /// Benchmark: copy polyline to array.
     /// </summary>
     /// <returns>The encoded polyline.</returns>
     [Benchmark]
@@ -127,7 +135,7 @@ public void Polyline_CopyTo() {
     }
 
     /// <summary>
-    /// Benchmarks the encoding of an enumeration of coordinates into a polyline.
+    /// Benchmark: compare polyline with same value.
     /// </summary>
     /// <returns>The encoded polyline.</returns>
     [Benchmark]
@@ -139,7 +147,7 @@ public void Polyline_Equals_SameValue() {
     }
 
     /// <summary>
-    /// Benchmarks the encoding of an enumeration of coordinates into a polyline.
+    /// Benchmark: compare polyline with different value.
     /// </summary>
     /// <returns>The encoded polyline.</returns>
     [Benchmark]
@@ -152,7 +160,7 @@ public void Polyline_Equals_DifferentValue() {
 
 
     /// <summary>
-    /// Benchmarks the encoding of an enumeration of coordinates into a polyline.
+    /// Benchmark: compare polyline with different type.
     /// </summary>
     /// <returns>The encoded polyline.</returns>
     [Benchmark]

benchmarks/PolylineAlgorithm.Benchmarks/PolylineDecoderBenchmark.cs

@@ -12,7 +12,7 @@ namespace PolylineAlgorithm.Benchmarks;
 using PolylineAlgorithm.Utility;
 
 /// <summary>
-/// Benchmarks for the <see cref="PolylineDecoder"/> class.
+/// Benchmarks for <see cref="PolylineDecoder"/>.
 /// </summary>
 public class PolylineDecoderBenchmark {
     private readonly Consumer _consumer = new();
@@ -22,34 +22,34 @@ public class PolylineDecoderBenchmark {
 
 #pragma warning disable CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring as nullable.
     /// <summary>
-    /// Gets the string value representing the encoded polyline.
+    /// Polyline instance for benchmarks.
     /// </summary>
     public Polyline Polyline { get; private set; }
 
     /// <summary>
-    /// Gets the string value representing the encoded polyline.
+    /// Encoded polyline as string.
     /// </summary>
     public string String { get; private set; }
 
     /// <summary>
-    /// Gets the string value representing the encoded polyline.
+    /// Encoded polyline as char array.
     /// </summary>
     public char[] CharArray { get; private set; }
 
     /// <summary>
-    /// Gets the string value representing the encoded polyline.
+    /// Encoded polyline as read-only memory.
     /// </summary>
     public ReadOnlyMemory<char> Memory { get; private set; }
 
 #pragma warning restore CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring as nullable.
 
     /// <summary>
-    /// The polyline decoder instance.
+    /// Polyline decoder instance.
     /// </summary>
     public readonly PolylineDecoder Decoder = new();
 
     /// <summary>
-    /// Sets up the data for the benchmarks.
+    /// Sets up benchmark data.
     /// </summary>
     [GlobalSetup]
     public void SetupData() {
@@ -60,7 +60,7 @@ public void SetupData() {
     }
 
     /// <summary>
-    /// Benchmarks the decoding of a polyline from a string.
+    /// Benchmark: decode polyline instance.
     /// </summary>
     [Benchmark]
     public void PolylineDecoder_Decode_Polyline() {
@@ -70,7 +70,7 @@ public void PolylineDecoder_Decode_Polyline() {
     }
 
     /// <summary>
-    /// Benchmarks the decoding of a polyline from a string.
+    /// Benchmark: decode from string.
     /// </summary>
     [Benchmark]
     public void PolylineDecoder_Decode_String() {
@@ -80,7 +80,7 @@ public void PolylineDecoder_Decode_String() {
     }
 
     /// <summary>
-    /// Benchmarks the decoding of a polyline from a string.
+    /// Benchmark: decode from char array.
     /// </summary>
     [Benchmark]
     public void PolylineDecoder_Decode_CharArray() {
@@ -90,7 +90,7 @@ public void PolylineDecoder_Decode_CharArray() {
     }
 
     /// <summary>
-    /// Benchmarks the decoding of a polyline from a string.
+    /// Benchmark: decode from memory.
     /// </summary>
     [Benchmark]
     public void PolylineDecoder_Decode_Memory() {

benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncoderBenchmark.cs

@@ -13,39 +13,42 @@ namespace PolylineAlgorithm.Benchmarks;
 using System.Collections.Generic;
 
 /// <summary>
-/// Benchmarks for the <see cref="PolylineEncoder"/> class.
+/// Benchmarks for <see cref="PolylineEncoder"/>.
 /// </summary>
 public class PolylineEncoderBenchmark {
     private readonly Consumer _consumer = new();
 
+    /// <summary>
+    /// Number of coordinates for benchmarks.
+    /// </summary>
     [Params(1, 100, 1_000)]
     public int CoordinatesCount;
 
 #pragma warning disable CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring as nullable.
     /// <summary>
-    /// Gets the list of coordinates to be encoded.
+    /// Coordinates as list.
     /// </summary>
     public List<Coordinate> List { get; private set; }
 
     /// <summary>
-    /// Gets the list of coordinates to be encoded.
+    /// Coordinates as array.
     /// </summary>
     public Coordinate[] Array { get; private set; }
 
     /// <summary>
-    /// Gets the list of coordinates to be encoded.
+    /// Coordinates as read-only memory.
     /// </summary>
     public ReadOnlyMemory<Coordinate> Memory { get; private set; }
 
 #pragma warning restore CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring as nullable.
 
     /// <summary>
-    /// The polyline encoder instance.
+    /// Polyline encoder instance.
     /// </summary>
     public readonly PolylineEncoder Encoder = new();
 
     /// <summary>
-    /// Sets up the data for the benchmarks.
+    /// Sets up benchmark data.
     /// </summary>
     [GlobalSetup]
     public void SetupData() {
@@ -55,9 +58,9 @@ public void SetupData() {
     }
 
     /// <summary>
-    /// Benchmarks the encoding of a list of coordinates into a polyline.
+    /// Benchmark: encode coordinates from span.
     /// </summary>
-    /// <returns>The encoded polyline.</returns>
+    /// <returns>Encoded polyline.</returns>
     [Benchmark]
     public void PolylineEncoder_Encode_Span() {
         var polyline = Encoder
@@ -67,9 +70,9 @@ public void PolylineEncoder_Encode_Span() {
     }
 
     /// <summary>
-    /// Benchmarks the encoding of a list of coordinates into a polyline.
+    /// Benchmark: encode coordinates from array.
     /// </summary>
-    /// <returns>The encoded polyline.</returns>
+    /// <returns>Encoded polyline.</returns>
     [Benchmark]
     public void PolylineEncoder_Encode_Array() {
         var polyline = Encoder
@@ -79,9 +82,9 @@ public void PolylineEncoder_Encode_Array() {
     }
 
     /// <summary>
-    /// Benchmarks the encoding of a list of coordinates into a polyline.
+    /// Benchmark: encode coordinates from list.
     /// </summary>
-    /// <returns>The encoded polyline.</returns>
+    /// <returns>Encoded polyline.</returns>
     [Benchmark]
     public void PolylineEncoder_Encode_List() {
         var polyline = Encoder

benchmarks/PolylineAlgorithm.Benchmarks/Program.cs

@@ -8,13 +8,13 @@ namespace PolylineAlgorithm.Benchmarks;
 using BenchmarkDotNet.Running;
 
 /// <summary>
-/// The main entry point for the benchmark application.
+/// Main entry point for benchmarks.
 /// </summary>
 internal class Program {
     /// <summary>
-    /// The main method that runs the benchmarks.
+    /// Runs the benchmarks.
     /// </summary>
-    /// <param name="args">The command-line arguments.</param>
+    /// <param name="args">Command-line arguments.</param>
     static void Main(string[] args) {
         BenchmarkSwitcher
             .FromAssembly(typeof(Program).Assembly)

src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs

@@ -64,6 +64,8 @@ protected AbstractPolylineEncoder(PolylineEncodingOptions options) {
     /// <exception cref="ArgumentException">
     /// Thrown when <paramref name="coordinates"/> is an empty enumeration.
     /// </exception>
+    /// <exception cref="InternalBufferOverflowException"></exception>
+    /// <exception cref="InvalidOperationException"></exception>
     public TPolyline Encode(ReadOnlySpan<TCoordinate> coordinates) {
         const string OperationName = nameof(Encode);