updated documenation

Author: Petr Sramek

src/PolylineAlgorithm/Coordinate.cs

@@ -131,4 +131,4 @@ public bool Equals(Coordinate other) {
     }
 
     #endregion
-}
+}

src/PolylineAlgorithm/IPolylineDecoder.cs

@@ -8,13 +8,14 @@ namespace PolylineAlgorithm;
 using System.Collections.Generic;
 
 /// <summary>
-/// Defines method to decode a polyline.
+/// Defines a method to decode an encoded polyline into a set of coordinates.
 /// </summary>
 public interface IPolylineDecoder {
     /// <summary>
     /// Converts an encoded polyline to a set of coordinates.
     /// </summary>
     /// <param name="polyline">An encoded polyline to decode.</param>
-    /// <returns>A set of coordinates.</returns>
+    /// <returns>A set of coordinates represented by the encoded polyline.</returns>
     IEnumerable<Coordinate> Decode(ref readonly Polyline polyline);
-}
+}
+

src/PolylineAlgorithm/IPolylineEncoder.cs

@@ -8,13 +8,13 @@ namespace PolylineAlgorithm;
 using System.Collections.Generic;
 
 /// <summary>
-/// Defines method to encode a set of coordinates.
+/// Defines a method to encode a set of coordinates into an encoded polyline.
 /// </summary>
 public interface IPolylineEncoder {
     /// <summary>
     /// Converts a set of coordinates to an encoded polyline.
     /// </summary>
     /// <param name="coordinates">A set of coordinates to encode.</param>
-    /// <returns>An encoded polyline.</returns>
+    /// <returns>An encoded polyline representing the set of coordinates.</returns>
     Polyline Encode(IEnumerable<Coordinate> coordinates);
-}
+}

src/PolylineAlgorithm/Internal/PolylineReader.cs

@@ -8,23 +8,44 @@ namespace PolylineAlgorithm.Internal;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 
+/// <summary>
+/// Provides functionality to read and decode a polyline.
+/// </summary>
 [StructLayout(LayoutKind.Auto)]
 internal ref struct PolylineReader {
     private ReaderState _state = new();
     private readonly ReadOnlySpan<char> _polyline;
 
+    /// <summary>
+    /// Creates a new instance of the <see cref="PolylineReader"/> struct with an empty polyline.
+    /// </summary>
     public PolylineReader() {
-        _polyline = [];
+        _polyline = ReadOnlySpan<char>.Empty;
     }
 
+    /// <summary>
+    /// Creates a new instance of the <see cref="PolylineReader"/> struct with the specified polyline.
+    /// </summary>
+    /// <param name="polyline">The polyline to read.</param>
     public PolylineReader(ref readonly Polyline polyline) {
         _polyline = polyline.Span;
     }
 
+    /// <summary>
+    /// Gets a value indicating whether there are more characters to read.
+    /// </summary>
     public readonly bool CanRead => _state.Position < _polyline.Length;
 
+    /// <summary>
+    /// Gets the current position of the reader.
+    /// </summary>
     public readonly int Position => _state.Position;
 
+    /// <summary>
+    /// Reads the next coordinate from the polyline.
+    /// </summary>
+    /// <returns>The next <see cref="Coordinate"/>.</returns>
+    /// <exception cref="InvalidReaderStateException">Thrown when the reader is in an invalid state.</exception>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public Coordinate Read() {
         InvalidReaderStateException.ThrowIfCannotRead(CanRead, Position, _polyline.Length);
@@ -44,23 +65,43 @@ static double Precise(ref int value) {
         }
     }
 
+    /// <summary>
+    /// Advances the reader to the next character.
+    /// </summary>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     void Advance() {
         _state.Position += 1;
     }
 
+    /// <summary>
+    /// Sets the current latitude and longitude.
+    /// </summary>
+    /// <param name="latitude">The latitude value.</param>
+    /// <param name="longitude">The longitude value.</param>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     void SetCurrent(ref readonly int latitude, ref readonly int longitude) {
         _state.Latitude = latitude;
         _state.Longitude = longitude;
     }
 
+    /// <summary>
+    /// Gets the current latitude and longitude.
+    /// </summary>
+    /// <param name="latitude">The latitude value.</param>
+    /// <param name="longitude">The longitude value.</param>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     readonly void GetCurrent(out int latitude, out int longitude) {
         latitude = _state.Latitude;
         longitude = _state.Longitude;
     }
 
+    /// <summary>
+    /// Reads the next value from the polyline.
+    /// </summary>
+    /// <param name="value">The current value.</param>
+    /// <returns>The next value.</returns>
+    /// <exception cref="InvalidReaderStateException">Thrown when the reader is in an invalid state.</exception>
+    /// <exception cref="InvalidPolylineException">Thrown when the polyline is malformed.</exception>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     int ReadNext(ref readonly int value) {
         int chunk;
@@ -82,17 +123,31 @@ int ReadNext(ref readonly int value) {
         return value + ((sum & 1) == 1 ? ~(sum >> 1) : sum >> 1);
     }
 
+    /// <summary>
+    /// Represents the state of the reader.
+    /// </summary>
     [StructLayout(LayoutKind.Sequential, Pack = 4, Size = 12)]
     private ref struct ReaderState {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ReaderState"/> struct.
+        /// </summary>
         public ReaderState() {
             Position = Latitude = Longitude = 0;
         }
 
-
+        /// <summary>
+        /// Gets or sets the current position of the reader.
+        /// </summary>
         public int Position { get; set; }
 
+        /// <summary>
+        /// Gets or sets the current latitude value.
+        /// </summary>
         public int Latitude { get; set; }
 
+        /// <summary>
+        /// Gets or sets the current longitude value.
+        /// </summary>
         public int Longitude { get; set; }
     }
-}
+}

src/PolylineAlgorithm/Internal/PolylineWriter.cs

@@ -9,19 +9,38 @@ namespace PolylineAlgorithm.Internal;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 
+/// <summary>
+/// Provides functionality to write and encode a polyline.
+/// </summary>
 [StructLayout(LayoutKind.Auto)]
 internal ref struct PolylineWriter {
     private WriterState _state = new();
     private Memory<char> _buffer;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PolylineWriter"/> struct with the specified buffer.
+    /// </summary>
+    /// <param name="buffer">The buffer to write to.</param>
     public PolylineWriter(ref readonly Memory<char> buffer) {
         _buffer = buffer;
     }
 
+    /// <summary>
+    /// Gets a value indicating whether there is space left in the buffer to write.
+    /// </summary>
     public readonly bool CanWrite => _state.Position < _buffer.Length;
 
+    /// <summary>
+    /// Gets the current position of the writer.
+    /// </summary>
     public readonly int Position => _state.Position;
 
+    /// <summary>
+    /// Writes the specified coordinate to the buffer.
+    /// </summary>
+    /// <param name="coordinate">The coordinate to write.</param>
+    /// <exception cref="InvalidCoordinateException">Thrown when the coordinate is invalid.</exception>
+    /// <exception cref="InvalidWriterStateException">Thrown when the writer is in an invalid state.</exception>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public void Write(ref readonly Coordinate coordinate) {
         InvalidCoordinateException.ThrowIfNotValid(coordinate);
@@ -41,6 +60,11 @@ static void Imprecise(double value, out int result) {
         }
     }
 
+    /// <summary>
+    /// Writes the next value to the buffer.
+    /// </summary>
+    /// <param name="value">The value to write.</param>
+    /// <exception cref="InvalidWriterStateException">Thrown when the writer is in an invalid state.</exception>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     void WriteNext(ref readonly int value) {
         int rem = value << 1;
@@ -57,6 +81,11 @@ void WriteNext(ref readonly int value) {
         WriteChar(Convert.ToChar(rem + Defaults.Algorithm.QuestionMark));
     }
 
+    /// <summary>
+    /// Writes a character to the buffer.
+    /// </summary>
+    /// <param name="value">The character to write.</param>
+    /// <exception cref="InvalidWriterStateException">Thrown when the writer is in an invalid state.</exception>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     void WriteChar(char value) {
         InvalidWriterStateException.ThrowIfCannotWrite(CanWrite, Position, _buffer.Length);
@@ -65,6 +94,13 @@ void WriteChar(char value) {
         _state.Position += 1;
     }
 
+    /// <summary>
+    /// Updates the current latitude and longitude values and calculates their differences.
+    /// </summary>
+    /// <param name="latitude">The latitude value.</param>
+    /// <param name="longitude">The longitude value.</param>
+    /// <param name="latDiff">The difference in latitude.</param>
+    /// <param name="longDiff">The difference in longitude.</param>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     void UpdateCurrent(ref readonly int latitude, ref readonly int longitude, out int latDiff, out int longDiff) {
         latDiff = latitude - _state.Latitude;
@@ -74,22 +110,41 @@ void UpdateCurrent(ref readonly int latitude, ref readonly int longitude, out in
         _state.Longitude = longitude;
     }
 
+    /// <summary>
+    /// Converts the buffer to a <see cref="Polyline"/> instance.
+    /// </summary>
+    /// <returns>The <see cref="Polyline"/> instance.</returns>
     public readonly Polyline ToPolyline() {
         ReadOnlyMemory<char> buffer = _buffer[.._state.Position];
         var polyline = Polyline.FromMemory(buffer);
         return polyline;
     }
 
+    /// <summary>
+    /// Represents the state of the writer.
+    /// </summary>
     [StructLayout(LayoutKind.Sequential, Pack = 4, Size = 12)]
     private ref struct WriterState {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="WriterState"/> struct.
+        /// </summary>
         public WriterState() {
             Position = Latitude = Longitude = 0;
         }
 
+        /// <summary>
+        /// Gets or sets the current position of the writer.
+        /// </summary>
         public int Position { get; set; }
 
+        /// <summary>
+        /// Gets or sets the current latitude value.
+        /// </summary>
         public int Latitude { get; set; }
 
+        /// <summary>
+        /// Gets or sets the current longitude value.
+        /// </summary>
         public int Longitude { get; set; }
     }
-}
+}

src/PolylineAlgorithm/InvalidCoordinateException.cs

@@ -11,26 +11,36 @@ namespace PolylineAlgorithm;
 using System.Diagnostics.CodeAnalysis;
 
 /// <summary>
-/// Represents error that is caused by invalid coordinate.
+/// Represents an error that is caused by an invalid coordinate.
 /// </summary>
 [SuppressMessage("Design", "CA1032:Implement standard exception constructors", Justification = "Internal use only.")]
 [DebuggerDisplay($"{nameof(InvalidCoordinateException)}: {{ToString()}}")]
 public sealed class InvalidCoordinateException : Exception {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="InvalidCoordinateException"/> class with the specified coordinate and error message.
+    /// </summary>
+    /// <param name="coordinate">The coordinate that caused the exception.</param>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
     private InvalidCoordinateException(Coordinate coordinate, string message)
         : base(message) {
         Coordinate = coordinate;
     }
 
     /// <summary>
-    /// Coordinate that caused the exception.
+    /// Gets the coordinate that caused the exception.
     /// </summary>
     public Coordinate Coordinate { get; }
 
+    /// <summary>
+    /// Throws an <see cref="InvalidCoordinateException"/> if the specified coordinate is not valid.
+    /// </summary>
+    /// <param name="coordinate">The coordinate to validate.</param>
+    /// <exception cref="InvalidCoordinateException">Thrown when the coordinate is invalid.</exception>
     internal static void ThrowIfNotValid(Coordinate coordinate) {
         if (coordinate.IsValid) {
             return;
         }
 
         throw new InvalidCoordinateException(coordinate, string.Format(ExceptionMessageResource.CoordinateIsOutOfRangeMessageFormat, coordinate.Latitude, coordinate.Longitude));
     }
-}
+}

src/PolylineAlgorithm/InvalidPolylineException.cs

@@ -12,15 +12,24 @@ namespace PolylineAlgorithm;
 using System.Diagnostics.CodeAnalysis;
 
 /// <summary>
-/// Represents error that is caused by malformed polyline.
+/// Represents an error that is caused by a malformed polyline.
 /// </summary>
 [SuppressMessage("Design", "CA1032:Implement standard exception constructors", Justification = "Internal use only.")]
 [DebuggerDisplay($"{nameof(InvalidPolylineException)}: {{ToString()}}")]
 public sealed class InvalidPolylineException : Exception {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="InvalidPolylineException"/> class with the specified error message.
+    /// </summary>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
     private InvalidPolylineException(string message)
         : base(message) { }
 
+    /// <summary>
+    /// Throws an <see cref="InvalidPolylineException"/> with a message indicating the position of the error in the polyline.
+    /// </summary>
+    /// <param name="position">The position in the polyline where the error occurred.</param>
+    /// <exception cref="InvalidPolylineException">Always thrown to indicate a malformed polyline.</exception>
     internal static void Throw(int position) {
         throw new InvalidPolylineException(string.Format(ExceptionMessageResource.PolylineStringIsMalformedMessage, position));
     }
-}
+}

src/PolylineAlgorithm/InvalidReaderStateException.cs

@@ -12,14 +12,27 @@ namespace PolylineAlgorithm;
 using System.Diagnostics.CodeAnalysis;
 
 /// <summary>
-/// Represents error that is caused by invalid reader state.
+/// Represents an error that is caused by an invalid reader state.
 /// </summary>
 [SuppressMessage("Design", "CA1032:Implement standard exception constructors", Justification = "Internal use only.")]
 [DebuggerDisplay($"{nameof(InvalidReaderStateException)}: {{ToString()}}")]
 public sealed class InvalidReaderStateException : Exception {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="InvalidReaderStateException"/> class with the specified error message.
+    /// </summary>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
     private InvalidReaderStateException(string message)
         : base(message) { }
 
+    /// <summary>
+    /// Throws an <see cref="InvalidReaderStateException"/> if the reader cannot read from the polyline.
+    /// </summary>
+    /// <param name="canRead">A value indicating whether the reader can read from the polyline.</param>
+    /// <param name="readerPosition">The current position of the reader.</param>
+    /// <param name="polylineLength">The length of the polyline.</param>
+    /// <exception cref="InvalidReaderStateException">
+    /// Thrown when the reader cannot read from the polyline because the polyline is either empty or the reader has reached the end of the polyline.
+    /// </exception>
     internal static void ThrowIfCannotRead(bool canRead, int readerPosition, int polylineLength) {
         if (canRead) {
             return;
@@ -31,4 +44,5 @@ internal static void ThrowIfCannotRead(bool canRead, int readerPosition, int pol
             throw new InvalidReaderStateException(string.Format(ExceptionMessageResource.UnableToReadPolylineAtPositionMessageFormat, readerPosition, polylineLength));
         }
     }
-}
+}
+