fix: update stale XML comments and restore PolylineEncoderBenchmark

- Replace <see cref="Coordinate"/> and <see cref="Polyline"/> references in
  RandomValueProvider.cs and StaticValueProvider.cs with plain descriptions
  (those types no longer exist)
- Add missing <param name="cancellationToken"> tag in AbstractPolylineEncoder.Encode
  (fixes CS1573 warning)
- Uncomment and rewrite PolylineEncoderBenchmark.cs: add StringPolylineEncoder
  inner class, fix broken _encoder references in Span/Array/List benchmarks,
  align with IPolylineEncoder<TCoordinate, TPolyline> generic API

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/cd24bd09-954c-4853-95b0-1d634853b58a

Co-authored-by: petesramek <2333452+petesramek@users.noreply.github.com>

Author: Copilot

benchmarks/PolylineAlgorithm.Benchmarks/PolylineEncoderBenchmark.cs

@@ -1,103 +1,92 @@
-////
-//// Copyright © Pete Sramek. All rights reserved.
-//// Licensed under the MIT License. See LICENSE file in the project root for full license information.
-////
-
-//namespace PolylineAlgorithm.Benchmarks;
-
-//using BenchmarkDotNet.Attributes;
-//using BenchmarkDotNet.Engines;
-//using PolylineAlgorithm.Utility;
-//using System.Collections.Generic;
-
-///// <summary>
-///// 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 { get; set; }
-
-//#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>
-//    /// Coordinates as list.
-//    /// </summary>
-//    public List<(double Latitude, double Longitude)> List { get; private set; }
-
-//    /// <summary>
-//    /// Coordinates as array.
-//    /// </summary>
-//    public (double Latitude, double Longitude)[] Array { get; private set; }
-
-//    /// <summary>
-//    /// Coordinates as read-only memory.
-//    /// </summary>
-//    public ReadOnlyMemory<(double Latitude, double Longitude)> 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>
-//    /// Polyline encoder instance.
-//    /// </summary>
-//    private readonly StringPolylineEncoder _stringEncoder = new();
-
-//    /// <summary>
-//    /// Polyline encoder instance.
-//    /// </summary>
-//    private readonly CharArrayPolylineEncoder _charArrayEncoder = new();
-
-//    /// <summary>
-//    /// Polyline encoder instance.
-//    /// </summary>
-//    private readonly MemoryPolylineEncoder _memoryEncoder = new();
-
-//    /// <summary>
-//    /// Sets up benchmark data.
-//    /// </summary>
-//    [GlobalSetup]
-//    public void SetupData() {
-//        List = [.. RandomValueProvider.GetCoordinates(CoordinatesCount).Select(c => (c.Latitude, c.Longitude))];
-//        Array = [.. List];
-//        Memory = Array.AsMemory();
-//    }
-
-//    /// <summary>
-//    /// Benchmark: encode coordinates from span.
-//    /// </summary>
-//    /// <returns>Encoded polyline.</returns>
-//    [Benchmark]
-//    public void PolylineEncoder_Encode_Span() {
-//        var polyline = _encoder
-//            .Encode(Memory.Span!);
-
-//        _consumer.Consume(polyline);
-//    }
-
-//    /// <summary>
-//    /// Benchmark: encode coordinates from array.
-//    /// </summary>
-//    /// <returns>Encoded polyline.</returns>
-//    [Benchmark]
-//    public void PolylineEncoder_Encode_Array() {
-//        var polyline = _encoder
-//            .Encode(Array!);
-
-//        _consumer.Consume(polyline);
-//    }
-
-//    /// <summary>
-//    /// Benchmark: encode coordinates from list.
-//    /// </summary>
-//    /// <returns>Encoded polyline.</returns>
-//    [Benchmark]
-//    public void PolylineEncoder_Encode_List() {
-//        var polyline = _encoder
-//            .Encode(List!);
-
-//        _consumer.Consume(polyline);
-//    }
-//}
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.Benchmarks;
+
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Engines;
+using PolylineAlgorithm.Abstraction;
+using PolylineAlgorithm.Extensions;
+using PolylineAlgorithm.Utility;
+using System.Collections.Generic;
+
+/// <summary>
+/// Benchmarks for <see cref="AbstractPolylineEncoder{TCoordinate, TPolyline}"/>.
+/// </summary>
+public class PolylineEncoderBenchmark {
+    private readonly Consumer _consumer = new();
+
+    /// <summary>
+    /// Number of coordinates for benchmarks.
+    /// </summary>
+    [Params(1, 100, 1_000)]
+    public int CoordinatesCount { get; set; }
+
+#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>
+    /// Coordinates as list.
+    /// </summary>
+    public List<(double Latitude, double Longitude)> List { get; private set; }
+
+    /// <summary>
+    /// Coordinates as array.
+    /// </summary>
+    public (double Latitude, double Longitude)[] Array { get; private set; }
+
+    /// <summary>
+    /// Coordinates as read-only memory.
+    /// </summary>
+    public ReadOnlyMemory<(double Latitude, double Longitude)> 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>
+    /// Polyline encoder instance.
+    /// </summary>
+    private readonly StringPolylineEncoder _encoder = new();
+
+    /// <summary>
+    /// Sets up benchmark data.
+    /// </summary>
+    [GlobalSetup]
+    public void SetupData() {
+        List = [.. RandomValueProvider.GetCoordinates(CoordinatesCount)];
+        Array = [.. List];
+        Memory = Array.AsMemory();
+    }
+
+    /// <summary>
+    /// Benchmark: encode coordinates from span.
+    /// </summary>
+    [Benchmark]
+    public void PolylineEncoder_Encode_Span() {
+        var polyline = _encoder.Encode(Memory.Span);
+        _consumer.Consume(polyline);
+    }
+
+    /// <summary>
+    /// Benchmark: encode coordinates from array.
+    /// </summary>
+    [Benchmark]
+    public void PolylineEncoder_Encode_Array() {
+        var polyline = _encoder.Encode(Array);
+        _consumer.Consume(polyline);
+    }
+
+    /// <summary>
+    /// Benchmark: encode coordinates from list.
+    /// </summary>
+    [Benchmark]
+    public void PolylineEncoder_Encode_List() {
+        var polyline = _encoder.Encode(List);
+        _consumer.Consume(polyline);
+    }
+
+    private sealed class StringPolylineEncoder : AbstractPolylineEncoder<(double Latitude, double Longitude), string> {
+        protected override string CreatePolyline(ReadOnlyMemory<char> polyline) => polyline.ToString();
+        protected override double GetLatitude((double Latitude, double Longitude) current) => current.Latitude;
+        protected override double GetLongitude((double Latitude, double Longitude) current) => current.Longitude;
+    }
+}

src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs

@@ -61,6 +61,9 @@ protected AbstractPolylineEncoder(PolylineEncodingOptions options) {
     /// <param name="coordinates">
     /// The collection of <typeparamref name="TCoordinate"/> objects to encode.
     /// </param>
+    /// <param name="cancellationToken">
+    /// A <see cref="CancellationToken"/> that can be used to cancel the encoding operation.
+    /// </param>
     /// <returns>
     /// An instance of <typeparamref name="TPolyline"/> representing the encoded coordinates.
     /// </returns>

utilities/PolylineAlgorithm.Utility/RandomValueProvider.cs

@@ -23,11 +23,11 @@ internal static class RandomValueProvider {
     private static readonly PolylineEncoder _encoder = new();
 
     /// <summary>
-    /// Gets a collection of random <see cref="Coordinate"/> instances of the specified count.
+    /// Gets a collection of random latitude/longitude tuples of the specified count.
     /// The same collection is cached and reused for the same count value.
     /// </summary>
     /// <param name="count">The number of coordinates to generate.</param>
-    /// <returns>An enumerable collection of random <see cref="Coordinate"/> objects.</returns>
+    /// <returns>An enumerable collection of random latitude/longitude tuples.</returns>
     public static IEnumerable<(double Latitude, double Longitude)> GetCoordinates(int count) {
         var entry = GetCaheEntry(count);
 
@@ -39,11 +39,11 @@ internal static class RandomValueProvider {
     }
 
     /// <summary>
-    /// Gets a <see cref="Polyline"/> representing the encoded polyline for a random collection of coordinates of the specified count.
+    /// Gets the encoded polyline string for a random collection of coordinates of the specified count.
     /// The same polyline is cached and reused for the same count value.
     /// </summary>
     /// <param name="count">The number of coordinates to generate and encode.</param>
-    /// <returns>A <see cref="Polyline"/> representing the encoded polyline.</returns>
+    /// <returns>A <see cref="string"/> representing the encoded polyline.</returns>
     public static string GetPolyline(int count) {
         var entry = GetCaheEntry(count);
 

utilities/PolylineAlgorithm.Utility/StaticValueProvider.cs

@@ -18,7 +18,7 @@ internal static class Valid {
         private const string Polyline = "???_gsia@_cidP??~fsia@?~fsia@~bidP?~bidP??_gsia@";
 
         /// <summary>
-        /// A predefined collection of <see cref="Coordinate"/> instances representing a closed path around the globe.
+        /// A predefined collection of latitude/longitude tuples representing a closed path around the globe.
         /// </summary>
         private static readonly IEnumerable<(double Latitude, double Longitude)> _coordinates = [
             new (0, 0),
@@ -32,17 +32,17 @@ internal static class Valid {
         ];
 
         /// <summary>
-        /// Gets the predefined collection of <see cref="Coordinate"/> instances.
+        /// Gets the predefined collection of latitude/longitude tuples.
         /// </summary>
-        /// <returns>An <see cref="IEnumerable{Coordinate}"/> containing the static coordinates.</returns>
+        /// <returns>An <see cref="IEnumerable{T}"/> of latitude/longitude tuples containing the static coordinates.</returns>
         public static IEnumerable<(double Latitude, double Longitude)> GetCoordinates() {
             return _coordinates;
         }
 
         /// <summary>
-        /// Gets the predefined <see cref="PolylineAlgorithm.Polyline"/> instance.
+        /// Gets the predefined encoded polyline string.
         /// </summary>
-        /// <returns>The static <see cref="PolylineAlgorithm.Polyline"/> value.</returns>
+        /// <returns>The static encoded polyline string.</returns>
         public static string GetPolyline() {
             return Polyline;
         }