Updated code documentation

Author: petesramek

src/PolylineAlgorithm/Abstraction/IPolylineDecoder.cs

@@ -8,13 +8,15 @@ namespace PolylineAlgorithm.Abstraction;
 using System.Collections.Generic;
 
 /// <summary>
-/// Defines a method to decode an encoded polyline into a set of coordinates.
+/// Defines a contract for decoding an encoded polyline into a collection of geographic coordinates.
 /// </summary>
 public interface IPolylineDecoder {
     /// <summary>
-    /// Converts an encoded polyline to a set of coordinates.
+    /// Decodes an encoded polyline string into a collection of geographic coordinates.
     /// </summary>
-    /// <param name="polyline">An encoded polyline to decode.</param>
-    /// <returns>A set of coordinates represented by the encoded polyline.</returns>
+    /// <param name="polyline">The <see cref="Polyline"/> instance representing the encoded polyline string.</param>
+    /// <returns>
+    /// An <see cref="IEnumerable{T}"/> of <see cref="Coordinate"/> objects representing the decoded geographic coordinates.
+    /// </returns>
     IEnumerable<Coordinate> Decode(Polyline polyline);
-}
+}

src/PolylineAlgorithm/Abstraction/IPolylineEncoder.cs

@@ -8,13 +8,15 @@ namespace PolylineAlgorithm.Abstraction;
 using System.Collections.Generic;
 
 /// <summary>
-/// Defines a method to encode a set of coordinates into an encoded polyline.
+/// Defines a contract for encoding a collection of geographic coordinates into an encoded polyline string.
 /// </summary>
 public interface IPolylineEncoder {
     /// <summary>
-    /// Converts a set of coordinates to an encoded polyline.
+    /// Encodes a collection of geographic coordinates into an encoded polyline string.
     /// </summary>
-    /// <param name="coordinates">A set of coordinates to encode.</param>
-    /// <returns>An encoded polyline representing the set of coordinates.</returns>
+    /// <param name="coordinates">A collection of <see cref="Coordinate"/> objects to encode.</param>
+    /// <returns>
+    /// A <see cref="Polyline"/> instance representing the encoded polyline string.
+    /// </returns>
     Polyline Encode(IEnumerable<Coordinate> coordinates);
-}
+}

src/PolylineAlgorithm/Extensions/PolylineDecoderExtensions.cs

@@ -4,7 +4,21 @@
 using System;
 using System.Collections.Generic;
 
+/// <summary>
+/// Provides extension methods for the <see cref="IPolylineDecoder"/> interface to simplify decoding operations.
+/// </summary>
 public static class PolylineDecoderExtensions {
+    /// <summary>
+    /// Decodes an encoded polyline string into a collection of geographic coordinates.
+    /// </summary>
+    /// <param name="decoder">The <see cref="IPolylineDecoder"/> instance used to decode the polyline.</param>
+    /// <param name="polyline">The encoded polyline string to decode.</param>
+    /// <returns>
+    /// An <see cref="IEnumerable{T}"/> of <see cref="Coordinate"/> objects representing the decoded geographic coordinates.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown if the <paramref name="decoder"/> is <see langword="null"/>.
+    /// </exception>
     public static IEnumerable<Coordinate> Decode(this IPolylineDecoder decoder, string polyline) {
         if (decoder is null) {
             throw new ArgumentNullException(nameof(decoder));
@@ -13,6 +27,17 @@ public static IEnumerable<Coordinate> Decode(this IPolylineDecoder decoder, stri
         return decoder.Decode(Polyline.FromString(polyline));
     }
 
+    /// <summary>
+    /// Decodes an encoded polyline represented as a character array into a collection of geographic coordinates.
+    /// </summary>
+    /// <param name="decoder">The <see cref="IPolylineDecoder"/> instance used to decode the polyline.</param>
+    /// <param name="polyline">The encoded polyline represented as a character array to decode.</param>
+    /// <returns>
+    /// An <see cref="IEnumerable{T}"/> of <see cref="Coordinate"/> objects representing the decoded geographic coordinates.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown if the <paramref name="decoder"/> is <see langword="null"/>.
+    /// </exception>
     public static IEnumerable<Coordinate> Decode(this IPolylineDecoder decoder, char[] polyline) {
         if (decoder is null) {
             throw new ArgumentNullException(nameof(decoder));

src/PolylineAlgorithm/Extensions/PolylineEncoderExtensions.cs

@@ -4,7 +4,22 @@
 using System;
 using System.Collections.Generic;
 
+/// <summary>
+/// Provides extension methods for the <see cref="IPolylineEncoder"/> interface to simplify encoding operations.
+/// </summary>
 public static class PolylineEncoderExtensions {
+    /// <summary>
+    /// Encodes a collection of geographic coordinates into an encoded polyline string.
+    /// </summary>
+    /// <typeparam name="Coordinate">The type representing a geographic coordinate.</typeparam>
+    /// <param name="encoder">The <see cref="IPolylineEncoder"/> instance used to encode the coordinates.</param>
+    /// <param name="coordinates">A collection of coordinates to encode.</param>
+    /// <returns>
+    /// A <see cref="Polyline"/> instance representing the encoded polyline string.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown if the <paramref name="encoder"/> is <see langword="null"/>.
+    /// </exception>
     public static Polyline Encode<Coordinate>(this IPolylineEncoder encoder, ICollection<Coordinate> coordinates) {
         if (encoder is null) {
             throw new ArgumentNullException(nameof(encoder));
@@ -13,6 +28,17 @@ public static Polyline Encode<Coordinate>(this IPolylineEncoder encoder, ICollec
         return encoder.Encode(coordinates);
     }
 
+    /// <summary>
+    /// Encodes an array of geographic coordinates into an encoded polyline string.
+    /// </summary>
+    /// <param name="encoder">The <see cref="IPolylineEncoder"/> instance used to encode the coordinates.</param>
+    /// <param name="coordinates">An array of coordinates to encode.</param>
+    /// <returns>
+    /// A <see cref="Polyline"/> instance representing the encoded polyline string.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown if the <paramref name="encoder"/> is <see langword="null"/>.
+    /// </exception>
     public static Polyline Encode(this IPolylineEncoder encoder, Coordinate[] coordinates) {
         if (encoder is null) {
             throw new ArgumentNullException(nameof(encoder));

src/PolylineAlgorithm/Internal/CoordinateVariance.cs

@@ -5,20 +5,40 @@
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 
+/// <summary>
+/// Represents the variance between consecutive geographic coordinates (latitude and longitude).
+/// This struct is used to calculate and store the differences between coordinate values.
+/// </summary>
 [DebuggerDisplay($"{{{nameof(ToString)}(),nq}}")]
 [StructLayout(LayoutKind.Auto)]
 internal struct CoordinateVariance {
     private (int Latitude, int Longitude) _current = (0, 0);
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CoordinateVariance"/> struct with the specified latitude and longitude values.
+    /// </summary>
+    /// <param name="latitude">The initial latitude value.</param>
+    /// <param name="longitude">The initial longitude value.</param>
     private CoordinateVariance(int latitude, int longitude) {
         Latitude = latitude;
         Longitude = longitude;
     }
 
+    /// <summary>
+    /// Gets the variance in latitude between the current and previous coordinates.
+    /// </summary>
     public int Latitude { get; private set; }
 
+    /// <summary>
+    /// Gets the variance in longitude between the current and previous coordinates.
+    /// </summary>
     public int Longitude { get; private set; }
 
+    /// <summary>
+    /// Updates the variance based on the next set of latitude and longitude values.
+    /// </summary>
+    /// <param name="latitude">The next latitude value.</param>
+    /// <param name="longitude">The next longitude value.</param>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public void Next(int latitude, int longitude) {
         Latitude = Variance(_current.Latitude, latitude);
@@ -27,6 +47,12 @@ public void Next(int latitude, int longitude) {
         _current = (latitude, longitude);
     }
 
+    /// <summary>
+    /// Calculates the variance between two coordinate values.
+    /// </summary>
+    /// <param name="initial">The initial coordinate value.</param>
+    /// <param name="next">The next coordinate value.</param>
+    /// <returns>The calculated variance between the two values.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     private static int Variance(int initial, int next) => (initial, next) switch {
         (0, 0) => 0,
@@ -38,6 +64,10 @@ public void Next(int latitude, int longitude) {
         ( > 0, > 0) => next - initial,
     };
 
+    /// <summary>
+    /// Returns a string representation of the coordinate variance.
+    /// </summary>
+    /// <returns>A string in the format: Variance: { Latitude: [int], Longitude: [int] }.</returns>
     public override readonly string ToString()
         => $"Variance: {{ Latitude: {Latitude}, Longitude: {Longitude} }}";
 }

src/PolylineAlgorithm/Internal/Defaults.cs

@@ -9,31 +9,33 @@ namespace PolylineAlgorithm.Internal;
 using System.Diagnostics.CodeAnalysis;
 
 /// <summary>
-/// Provides default values used in the Polyline Algorithm.
+/// Provides default values and constants used throughout the Polyline Algorithm.
+/// This class contains nested static classes for organizing defaults related to the algorithm,
+/// polyline encoding, and geographic coordinates.
 /// </summary>
 [ExcludeFromCodeCoverage]
 internal static class Defaults {
     /// <summary>
-    /// Contains default values related to the algorithm.
+    /// Contains default values and constants related to the polyline encoding algorithm.
     /// </summary>
     public static class Algorithm {
         /// <summary>
-        /// The coordinate rounding precision.
+        /// The coordinate rounding precision used in the polyline encoding algorithm.
         /// </summary>
         public const int Precision = 100_000;
 
         /// <summary>
-        /// The length of the shift used in the algorithm.
+        /// The bit shift length used in the polyline encoding algorithm.
         /// </summary>
         public const byte ShiftLength = 5;
 
         /// <summary>
-        /// The ASCII value for the question mark character.
+        /// The ASCII value for the question mark character ('?').
         /// </summary>
         public const byte QuestionMark = 63;
 
         /// <summary>
-        /// The ASCII value for the space character.
+        /// The ASCII value for the space character (' ').
         /// </summary>
         public const byte Space = 32;
 
@@ -44,36 +46,41 @@ public static class Algorithm {
     }
 
     /// <summary>
-    /// Contains default values related to polyline.
+    /// Contains default values and constants related to polyline encoding.
     /// </summary>
     public static class Polyline {
+        /// <summary>
+        /// An array of delimiters used in the polyline encoding process.
+        /// Each delimiter is derived by adding the ASCII value of the question mark ('?') to a range of integers.
+        /// </summary>
         public static readonly byte[] Delimiters = [.. Enumerable.Range(0, 32).Select(n => (byte)(n + Defaults.Algorithm.QuestionMark))];
 
         /// <summary>
-        /// The minimum length of an encoded coordinate.
+        /// The minimum length of an encoded coordinate in the polyline format.
         /// </summary>
         public const int MinEncodedCoordinateLength = 2;
+
         /// <summary>
-        /// The maximum length of an encoded coordinate.
+        /// The maximum length of an encoded coordinate in the polyline format.
         /// </summary>
         public const int MaxEncodedCoordinateLength = 12;
     }
 
     /// <summary>
-    /// Contains default values related to coordinates.
+    /// Contains default values and constants related to geographic coordinates.
     /// </summary>
     public static class Coordinate {
         /// <summary>
         /// Contains default values related to latitude.
         /// </summary>
         public static class Latitude {
             /// <summary>
-            /// The minimum value for latitude.
+            /// The minimum valid value for latitude, in degrees.
             /// </summary>
             public const sbyte Min = -Max;
 
             /// <summary>
-            /// The maximum value for latitude.
+            /// The maximum valid value for latitude, in degrees.
             /// </summary>
             public const byte Max = 90;
         }
@@ -83,29 +90,29 @@ public static class Latitude {
         /// </summary>
         public static class Longitude {
             /// <summary>
-            /// The minimum value for longitude.
+            /// The minimum valid value for longitude, in degrees.
             /// </summary>
             public const short Min = -Max;
 
             /// <summary>
-            /// The maximum value for longitude.
+            /// The maximum valid value for longitude, in degrees.
             /// </summary>
             public const byte Max = 180;
         }
 
         /// <summary>
-        /// Contains default ranges for latitude and longitude.
+        /// Contains default ranges for validating latitude and longitude values.
         /// </summary>
         public static class Range {
             /// <summary>
-            /// The validation range for latitude.
+            /// The default validation range for latitude values.
             /// </summary>
             public static readonly CoordinateRange Latitude = new(Coordinate.Latitude.Min, Coordinate.Latitude.Max);
 
             /// <summary>
-            /// The validation range for longitude.
+            /// The default validation range for longitude values.
             /// </summary>
             public static readonly CoordinateRange Longitude = new(Coordinate.Longitude.Min, Coordinate.Longitude.Max);
         }
     }
-}
+}

src/PolylineAlgorithm/Internal/PolylineBuilder.cs

@@ -3,11 +3,23 @@
 using System;
 using System.Runtime.InteropServices;
 
+/// <summary>
+/// Provides functionality to build a polyline from multiple segments of characters.
+/// This struct is used to efficiently construct a <see cref="Polyline"/> instance.
+/// </summary>
 [StructLayout(LayoutKind.Auto)]
 internal struct PolylineBuilder {
     private PolylineSegment? _initial;
     private PolylineSegment? _last;
 
+    /// <summary>
+    /// Appends a new segment of characters to the polyline being built.
+    /// </summary>
+    /// <param name="value">The segment of characters to append.</param>
+    /// <remarks>
+    /// This method creates a new <see cref="PolylineSegment"/> for the provided memory
+    /// and links it to the existing chain of segments.
+    /// </remarks>
     public void Append(ReadOnlyMemory<char> value) {
         var current = new PolylineSegment(value);
 
@@ -17,11 +29,18 @@ public void Append(ReadOnlyMemory<char> value) {
         _last = current;
     }
 
+    /// <summary>
+    /// Builds the final <see cref="Polyline"/> instance from the appended segments.
+    /// </summary>
+    /// <returns>
+    /// A <see cref="Polyline"/> instance representing the concatenated segments.
+    /// If no segments were appended, an empty <see cref="Polyline"/> is returned.
+    /// </returns>
     public readonly Polyline Build() {
         if (_initial is null) {
             return Polyline.FromMemory(ReadOnlyMemory<char>.Empty);
         }
 
         return Polyline.FromSequence(new(_initial, 0, _last, _last!.Memory.Length));
     }
-}
+}

src/PolylineAlgorithm/Internal/PolylineSegment.cs

@@ -2,16 +2,35 @@
 
 using System.Buffers;
 
+/// <summary>
+/// Represents a segment of a polyline, implemented as a linked list of memory segments.
+/// This class extends <see cref="ReadOnlySequenceSegment{T}"/> to support efficient handling of polyline data.
+/// </summary>
 internal class PolylineSegment : ReadOnlySequenceSegment<char> {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PolylineSegment"/> class with the specified memory and running index.
+    /// </summary>
+    /// <param name="memory">The memory segment to associate with this polyline segment.</param>
+    /// <param name="runningIndex">
+    /// The cumulative index of this segment within the polyline. Defaults to 0.
+    /// </param>
     public PolylineSegment(ReadOnlyMemory<char> memory, long runningIndex = 0) {
         Memory = memory;
         RunningIndex = runningIndex;
     }
 
+    /// <summary>
+    /// Appends a new memory segment to the current polyline segment.
+    /// </summary>
+    /// <param name="memory">The memory segment to append.</param>
     public void Append(ReadOnlyMemory<char> memory) {
         Append(new PolylineSegment(memory));
     }
 
+    /// <summary>
+    /// Appends another <see cref="PolylineSegment"/> to the current segment, forming a linked list.
+    /// </summary>
+    /// <param name="next">The next <see cref="PolylineSegment"/> to append.</param>
     public void Append(PolylineSegment next) {
         next.RunningIndex = RunningIndex + Memory.Length;
         Next = next;