added documentation and file headers

Author: petesramek

utilities/PolylineAlgorithm.Utility/RandomValueProvider.cs

@@ -1,15 +1,30 @@
-namespace PolylineAlgorithm.Utility;
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.Utility;
 
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
 using System.Linq;
 
+/// <summary>
+/// Provides random generation and caching of coordinate collections and their encoded polyline representations.
+/// Useful for testing and benchmarking polyline algorithms with reproducible random data.
+/// </summary>
 internal static class RandomValueProvider {
     private static readonly Random _random = new(DateTime.Now.Millisecond);
     private static readonly ConcurrentDictionary<int, PolylineCoordinateCollectionPair> _cache = new();
     private static readonly PolylineEncoder _encoder = new();
 
+    /// <summary>
+    /// Gets a collection of random <see cref="Coordinate"/> instances 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>
     public static IEnumerable<Coordinate> GetCoordinates(int count) {
         var entry = GetCaheEntry(count);
 
@@ -20,12 +35,25 @@ public static IEnumerable<Coordinate> GetCoordinates(int count) {
         }
     }
 
+    /// <summary>
+    /// Gets a <see cref="Polyline"/> representing the encoded polyline 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>
     public static Polyline GetPolyline(int count) {
         var entry = GetCaheEntry(count);
 
         return entry.Polyline;
     }
 
+    /// <summary>
+    /// Gets or creates a cached entry containing a collection of random coordinates and its encoded polyline for the specified count.
+    /// </summary>
+    /// <param name="count">The number of coordinates to generate and cache.</param>
+    /// <returns>
+    /// A <see cref="PolylineCoordinateCollectionPair"/> containing the coordinates and their encoded polyline.
+    /// </returns>
     private static PolylineCoordinateCollectionPair GetCaheEntry(int count) {
         if (_cache.TryGetValue(count, out var entry)) {
             return entry;
@@ -41,16 +69,36 @@ private static PolylineCoordinateCollectionPair GetCaheEntry(int count) {
         return entry;
     }
 
+    /// <summary>
+    /// Generates a random longitude value in the range [-180, 180), rounded to 5 decimal places.
+    /// </summary>
+    /// <returns>A random longitude value.</returns>
     private static double RandomLongitude() {
         return Math.Round(_random.Next(-180, 180) + _random.NextDouble(), 5);
     }
 
+    /// <summary>
+    /// Generates a random latitude value in the range [-90, 90), rounded to 5 decimal places.
+    /// </summary>
+    /// <returns>A random latitude value.</returns>
     private static double RandomLatitude() {
         return Math.Round(_random.Next(-90, 90) + _random.NextDouble(), 5);
     }
 
+    /// <summary>
+    /// Represents a pair of a collection of coordinates and its encoded polyline.
+    /// </summary>
+    /// <param name="coordinates">The collection of coordinates.</param>
+    /// <param name="polyline">The encoded polyline.</param>
     private readonly struct PolylineCoordinateCollectionPair(IEnumerable<Coordinate> coordinates, Polyline polyline) {
+        /// <summary>
+        /// Gets the collection of coordinates.
+        /// </summary>
         public IEnumerable<Coordinate> Coordinates { get; } = coordinates;
+
+        /// <summary>
+        /// Gets the encoded polyline.
+        /// </summary>
         public Polyline Polyline { get; } = polyline;
     }
 }

utilities/PolylineAlgorithm.Utility/StaticValueProvider.cs

@@ -1,9 +1,24 @@
-namespace PolylineAlgorithm.Utility;
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.Utility;
 
 using System.Collections.Generic;
 
+/// <summary>
+/// Provides static, predefined coordinate and polyline values for use in tests and benchmarks.
+/// </summary>
 internal static class StaticValueProvider {
+    /// <summary>
+    /// A predefined polyline instance representing a fixed encoded polyline string.
+    /// </summary>
     private static readonly Polyline _polyline = Polyline.FromString("???_gsia@_cidP??~fsia@?~fsia@~bidP?~bidP??_gsia@");
+
+    /// <summary>
+    /// A predefined collection of <see cref="Coordinate"/> instances representing a closed path around the globe.
+    /// </summary>
     private static readonly IEnumerable<Coordinate> _coordinates = [
         new (0, 0),
         new (0, 180),
@@ -15,10 +30,18 @@ internal static class StaticValueProvider {
         new (-90, 0)
     ];
 
+    /// <summary>
+    /// Gets the predefined collection of <see cref="Coordinate"/> instances.
+    /// </summary>
+    /// <returns>An <see cref="IEnumerable{Coordinate}"/> containing the static coordinates.</returns>
     public static IEnumerable<Coordinate> GetCoordinates() {
         return _coordinates;
     }
 
+    /// <summary>
+    /// Gets the predefined <see cref="Polyline"/> instance.
+    /// </summary>
+    /// <returns>The static <see cref="Polyline"/> value.</returns>
     public static Polyline GetPolyline() {
         return _polyline;
     }