updated documentation, added file headers

Author: petesramek

src/PolylineAlgorithm/Abstraction/IPolylineDecoder.cs

@@ -12,11 +12,13 @@ namespace PolylineAlgorithm.Abstraction;
 /// </summary>
 public interface IPolylineDecoder {
     /// <summary>
-    /// Decodes an encoded polyline string into a collection of geographic coordinates.
+    /// Decodes the specified encoded polyline into a sequence of geographic coordinates.
     /// </summary>
-    /// <param name="polyline">The <see cref="Polyline"/> instance representing the encoded polyline string.</param>
+    /// <param name="polyline">
+    /// The <see cref="Polyline"/> instance containing the encoded polyline string to decode.
+    /// </param>
     /// <returns>
-    /// An <see cref="IEnumerable{T}"/> of <see cref="Coordinate"/> objects representing the decoded geographic coordinates.
+    /// An <see cref="IEnumerable{T}"/> of <see cref="Coordinate"/> representing the decoded latitude and longitude pairs.
     /// </returns>
     IEnumerable<Coordinate> Decode(Polyline polyline);
 }

src/PolylineAlgorithm/Abstraction/IPolylineEncoder.cs

@@ -12,11 +12,13 @@ namespace PolylineAlgorithm.Abstraction;
 /// </summary>
 public interface IPolylineEncoder {
     /// <summary>
-    /// Encodes a collection of geographic coordinates into an encoded polyline string.
+    /// Encodes a sequence of geographic coordinates into an encoded polyline representation.
     /// </summary>
-    /// <param name="coordinates">A collection of <see cref="Coordinate"/> objects to encode.</param>
+    /// <param name="coordinates">
+    /// The collection of <see cref="Coordinate"/> instances to encode into a polyline.
+    /// </param>
     /// <returns>
-    /// A <see cref="Polyline"/> instance representing the encoded polyline string.
+    /// A <see cref="Polyline"/> containing the encoded polyline string that represents the input coordinates.
     /// </returns>
     Polyline Encode(IEnumerable<Coordinate> coordinates);
 }

src/PolylineAlgorithm/Coordinate.cs

@@ -12,51 +12,56 @@ namespace PolylineAlgorithm;
 using System.Globalization;
 using System.Runtime.InteropServices;
 /// <summary>
-/// Represents a latitude and longitude coordinate pair.
+/// Represents a geographic coordinate as a pair of latitude and longitude values.
 /// </summary>
 [DebuggerDisplay("{ToString()}")]
 [StructLayout(LayoutKind.Sequential, Pack = 8, Size = 16)]
 public readonly struct Coordinate : IEquatable<Coordinate> {
     /// <summary>
-    /// Initializes a new instance of the <see cref="Coordinate"/> struct with default values for <see cref="Latitude"/> and <see cref="Longitude"/>.
+    /// Initializes a new instance of the <see cref="Coordinate"/> struct with default values (0) for <see cref="Latitude"/> and <see cref="Longitude"/>.
     /// </summary>
     public Coordinate() {
         Latitude = default;
         Longitude = default;
     }
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="Coordinate"/> struct with specified latitude and longitude values.
+    /// Initializes a new instance of the <see cref="Coordinate"/> struct with the specified latitude and longitude values.
     /// </summary>
-    /// <param name="latitude">The latitude value, in degrees.</param>
-    /// <param name="longitude">The longitude value, in degrees.</param>
+    /// <param name="latitude">The latitude component, in degrees.</param>
+    /// <param name="longitude">The longitude component, in degrees.</param>
     public Coordinate(double latitude, double longitude) {
         Latitude = latitude;
         Longitude = longitude;
     }
 
     /// <summary>
-    /// Gets the latitude value of the coordinate, in degrees.
+    /// Gets the latitude component of the coordinate, in degrees.
     /// </summary>
     public double Latitude { get; }
 
     /// <summary>
-    /// Gets the longitude value of the coordinate, in degrees.
+    /// Gets the longitude component of the coordinate, in degrees.
     /// </summary>
     public double Longitude { get; }
 
     /// <summary>
-    /// Determines whether the coordinate is the default value (both <see cref="Latitude"/> and <see cref="Longitude"/> are 0).
+    /// Determines whether this coordinate is the default value (both <see cref="Latitude"/> and <see cref="Longitude"/> are 0).
     /// </summary>
-    /// <returns><see langword="true"/> if the coordinate is the default value; otherwise, <see langword="false"/>.</returns>
+    /// <returns>
+    /// <see langword="true"/> if both latitude and longitude are 0; otherwise, <see langword="false"/>.
+    /// </returns>
     public bool IsDefault()
         => Latitude == default
         && Longitude == default;
 
     /// <summary>
-    /// Determines whether the coordinate is valid by checking if both <see cref="Latitude"/> and <see cref="Longitude"/> are within their respective valid ranges.
+    /// Determines whether this coordinate is valid by checking if both <see cref="Latitude"/> and <see cref="Longitude"/>
+    /// are within their respective valid ranges as defined by the default <see cref="ICoordinateValidator"/>.
     /// </summary>
-    /// <returns><see langword="true"/> if the coordinate is valid; otherwise, <see langword="false"/>.</returns>
+    /// <returns>
+    /// <see langword="true"/> if the coordinate is within valid latitude and longitude ranges; otherwise, <see langword="false"/>.
+    /// </returns>
     public bool IsValid() => ICoordinateValidator.Default.IsValid(this);
 
     #region Overrides
@@ -70,9 +75,11 @@ public bool IsDefault()
     public override int GetHashCode() => HashCode.Combine(Latitude, Longitude);
 
     /// <summary>
-    /// Returns a string representation of the coordinate in the format: { Latitude: [double], Longitude: [double] }.
+    /// Returns a string representation of this coordinate in the format: <c>{ Latitude: [double], Longitude: [double] }</c>.
     /// </summary>
-    /// <returns>A string representation of the coordinate.</returns>
+    /// <returns>
+    /// A string representation of the coordinate.
+    /// </returns>
     [ExcludeFromCodeCoverage]
     public override string ToString() {
         return $"{{ {nameof(Latitude)}: {Latitude.ToString("G", CultureInfo.InvariantCulture)}, {nameof(Longitude)}: {Longitude.ToString("G", CultureInfo.InvariantCulture)} }}";
@@ -83,10 +90,12 @@ public override string ToString() {
     #region IEquatable<Coordinate> implementation
 
     /// <summary>
-    /// Determines whether the current coordinate is equal to another coordinate.
+    /// Indicates whether this coordinate is equal to another <see cref="Coordinate"/> instance.
     /// </summary>
-    /// <param name="other">The coordinate to compare with the current coordinate.</param>
-    /// <returns><see langword="true"/> if the coordinates are equal; otherwise, <see langword="false"/>.</returns>
+    /// <param name="other">The coordinate to compare with this instance.</param>
+    /// <returns>
+    /// <see langword="true"/> if both latitude and longitude are equal; otherwise, <see langword="false"/>.
+    /// </returns>
     public bool Equals(Coordinate other) {
         return Latitude == other.Latitude &&
                Longitude == other.Longitude;
@@ -101,7 +110,9 @@ public bool Equals(Coordinate other) {
     /// </summary>
     /// <param name="left">The first coordinate to compare.</param>
     /// <param name="right">The second coordinate to compare.</param>
-    /// <returns><see langword="true"/> if the coordinates are equal; otherwise, <see langword="false"/>.</returns>
+    /// <returns>
+    /// <see langword="true"/> if both coordinates are equal; otherwise, <see langword="false"/>.
+    /// </returns>
     [ExcludeFromCodeCoverage]
     public static bool operator ==(Coordinate left, Coordinate right) => left.Equals(right);
 
@@ -110,7 +121,9 @@ public bool Equals(Coordinate other) {
     /// </summary>
     /// <param name="left">The first coordinate to compare.</param>
     /// <param name="right">The second coordinate to compare.</param>
-    /// <returns><see langword="true"/> if the coordinates are not equal; otherwise, <see langword="false"/>.</returns>
+    /// <returns>
+    /// <see langword="true"/> if the coordinates are not equal; otherwise, <see langword="false"/>.
+    /// </returns>
     [ExcludeFromCodeCoverage]
     public static bool operator !=(Coordinate left, Coordinate right) => !(left == right);
 

src/PolylineAlgorithm/Extensions/PolylineDecoderExtensions.cs

@@ -1,23 +1,32 @@
-namespace PolylineAlgorithm.Extensions;
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.Extensions;
 
 using PolylineAlgorithm.Abstraction;
 using System;
 using System.Collections.Generic;
 
 /// <summary>
-/// Provides extension methods for the <see cref="IPolylineDecoder"/> interface to simplify decoding operations.
+/// Provides extension methods for the <see cref="IPolylineDecoder"/> interface to facilitate decoding encoded polylines.
 /// </summary>
 public static class PolylineDecoderExtensions {
     /// <summary>
-    /// Decodes an encoded polyline string into a collection of geographic coordinates.
+    /// Decodes an encoded polyline string into a sequence 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>
+    /// <param name="decoder">
+    /// The <see cref="IPolylineDecoder"/> instance used to perform the decoding operation.
+    /// </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.
+    /// An <see cref="IEnumerable{Coordinate}"/> containing the decoded latitude and longitude pairs.
     /// </returns>
     /// <exception cref="ArgumentNullException">
-    /// Thrown if the <paramref name="decoder"/> is <see langword="null"/>.
+    /// Thrown if <paramref name="decoder"/> is <see langword="null"/>.
     /// </exception>
     public static IEnumerable<Coordinate> Decode(this IPolylineDecoder decoder, string polyline) {
         if (decoder is null) {
@@ -28,15 +37,19 @@ public static IEnumerable<Coordinate> Decode(this IPolylineDecoder decoder, stri
     }
 
     /// <summary>
-    /// Decodes an encoded polyline represented as a character array into a collection of geographic coordinates.
+    /// Decodes an encoded polyline represented as a character array into a sequence 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>
+    /// <param name="decoder">
+    /// The <see cref="IPolylineDecoder"/> instance used to perform the decoding operation.
+    /// </param>
+    /// <param name="polyline">
+    /// The encoded polyline as a character array to decode.
+    /// </param>
     /// <returns>
-    /// An <see cref="IEnumerable{T}"/> of <see cref="Coordinate"/> objects representing the decoded geographic coordinates.
+    /// An <see cref="IEnumerable{Coordinate}"/> containing the decoded latitude and longitude pairs.
     /// </returns>
     /// <exception cref="ArgumentNullException">
-    /// Thrown if the <paramref name="decoder"/> is <see langword="null"/>.
+    /// Thrown if <paramref name="decoder"/> is <see langword="null"/>.
     /// </exception>
     public static IEnumerable<Coordinate> Decode(this IPolylineDecoder decoder, char[] polyline) {
         if (decoder is null) {

src/PolylineAlgorithm/Extensions/PolylineEncoderExtensions.cs

@@ -1,26 +1,34 @@
-namespace PolylineAlgorithm.Extensions;
+//
+// Copyright © Pete Sramek. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+//
+
+namespace PolylineAlgorithm.Extensions;
 
 using PolylineAlgorithm.Abstraction;
 using System;
 using System.Collections.Generic;
 
 /// <summary>
-/// Provides extension methods for the <see cref="IPolylineEncoder"/> interface to simplify encoding operations.
+/// Provides extension methods for the <see cref="IPolylineEncoder"/> interface to facilitate encoding geographic coordinates into polylines.
 /// </summary>
 public static class PolylineEncoderExtensions {
     /// <summary>
-    /// Encodes a collection of geographic coordinates into an encoded polyline string.
+    /// Encodes a collection of <see cref="Coordinate"/> instances into an encoded polyline.
     /// </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>
+    /// <param name="encoder">
+    /// The <see cref="IPolylineEncoder"/> instance used to perform the encoding operation.
+    /// </param>
+    /// <param name="coordinates">
+    /// The collection of <see cref="Coordinate"/> objects to encode.
+    /// </param>
     /// <returns>
-    /// A <see cref="Polyline"/> instance representing the encoded polyline string.
+    /// A <see cref="Polyline"/> representing the encoded polyline string for the provided coordinates.
     /// </returns>
     /// <exception cref="ArgumentNullException">
-    /// Thrown if the <paramref name="encoder"/> is <see langword="null"/>.
+    /// Thrown if <paramref name="encoder"/> is <see langword="null"/>.
     /// </exception>
-    public static Polyline Encode<Coordinate>(this IPolylineEncoder encoder, ICollection<Coordinate> coordinates) {
+    public static Polyline Encode(this IPolylineEncoder encoder, ICollection<Coordinate> coordinates) {
         if (encoder is null) {
             throw new ArgumentNullException(nameof(encoder));
         }
@@ -29,15 +37,19 @@ public static Polyline Encode<Coordinate>(this IPolylineEncoder encoder, ICollec
     }
 
     /// <summary>
-    /// Encodes an array of geographic coordinates into an encoded polyline string.
+    /// Encodes an array of <see cref="Coordinate"/> instances into an encoded polyline.
     /// </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>
+    /// <param name="encoder">
+    /// The <see cref="IPolylineEncoder"/> instance used to perform the encoding operation.
+    /// </param>
+    /// <param name="coordinates">
+    /// The array of <see cref="Coordinate"/> objects to encode.
+    /// </param>
     /// <returns>
-    /// A <see cref="Polyline"/> instance representing the encoded polyline string.
+    /// A <see cref="Polyline"/> representing the encoded polyline string for the provided coordinates.
     /// </returns>
     /// <exception cref="ArgumentNullException">
-    /// Thrown if the <paramref name="encoder"/> is <see langword="null"/>.
+    /// Thrown if <paramref name="encoder"/> is <see langword="null"/>.
     /// </exception>
     public static Polyline Encode(this IPolylineEncoder encoder, Coordinate[] coordinates) {
         if (encoder is null) {