Updated docs for version 1.0

Author: Copilot

api-reference/1.0/PolylineAlgorithm.Abstraction.AbstractPolylineDecoder-2.yml

@@ -3,7 +3,7 @@ title: Class AbstractPolylineDecoder<TPolyline, TCoordinate>
 body:
 - api1: Class AbstractPolylineDecoder<TPolyline, TCoordinate>
   id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L23
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L21
   metadata:
     uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2
     commentId: T:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2
@@ -56,15 +56,15 @@ body:
 - h2: Constructors
 - api3: AbstractPolylineDecoder()
   id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2__ctor
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L29
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L27
   metadata:
     uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.#ctor
     commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.#ctor
 - markdown: Initializes a new instance of the <xref href="PolylineAlgorithm.Abstraction.AbstractPolylineDecoder%602" data-throw-if-not-resolved="false"></xref> class with default encoding options.
 - code: protected AbstractPolylineDecoder()
 - api3: AbstractPolylineDecoder(PolylineEncodingOptions)
   id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2__ctor_PolylineAlgorithm_PolylineEncodingOptions_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L41
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L39
   metadata:
     uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.#ctor(PolylineAlgorithm.PolylineEncodingOptions)
     commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.#ctor(PolylineAlgorithm.PolylineEncodingOptions)
@@ -86,7 +86,7 @@ body:
 - h2: Properties
 - api3: Options
   id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2_Options
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L55
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L53
   metadata:
     uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.Options
     commentId: P:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.Options
@@ -100,7 +100,7 @@ body:
 - h2: Methods
 - api3: CreateCoordinate(double, double)
   id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2_CreateCoordinate_System_Double_System_Double_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L224
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L201
   metadata:
     uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.CreateCoordinate(System.Double,System.Double)
     commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.CreateCoordinate(System.Double,System.Double)
@@ -123,54 +123,17 @@ body:
   - type:
     - TCoordinate
     description: A <code class="typeparamref">TCoordinate</code> instance representing the specified geographic coordinate.
-- api3: Decode(TPolyline)
-  id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2_Decode__0_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L75
-  metadata:
-    uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.Decode(`0)
-    commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.Decode(`0)
-- markdown: Decodes an encoded <code class="typeparamref">TPolyline</code> into a sequence of <code class="typeparamref">TCoordinate</code> instances.
-- code: public IEnumerable<TCoordinate> Decode(TPolyline polyline)
-- h4: Parameters
-- parameters:
-  - name: polyline
-    type:
-    - TPolyline
-    description: The <code class="typeparamref">TPolyline</code> instance containing the encoded polyline string to decode.
-- h4: Returns
-- parameters:
-  - type:
-    - text: IEnumerable
-      url: https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1
-    - <
-    - TCoordinate
-    - '>'
-    description: An <xref href="System.Collections.Generic.IEnumerable%601" data-throw-if-not-resolved="false"></xref> of <code class="typeparamref">TCoordinate</code> representing the decoded latitude and longitude pairs.
-- h4: Exceptions
-- parameters:
-  - type:
-    - text: ArgumentNullException
-      url: https://learn.microsoft.com/dotnet/api/system.argumentnullexception
-    description: Thrown when <code class="paramref">polyline</code> is <a href="https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null">null</a>.
-  - type:
-    - text: ArgumentException
-      url: https://learn.microsoft.com/dotnet/api/system.argumentexception
-    description: Thrown when <code class="paramref">polyline</code> is empty.
-  - type:
-    - text: InvalidPolylineException
-      url: PolylineAlgorithm.Diagnostics.InvalidPolylineException.html
-    description: Thrown when the polyline format is invalid or malformed at a specific position.
 - api3: Decode(TPolyline, CancellationToken)
   id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2_Decode__0_System_Threading_CancellationToken_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L103
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L80
   metadata:
     uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.Decode(`0,System.Threading.CancellationToken)
     commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.Decode(`0,System.Threading.CancellationToken)
 - markdown: >-
     Decodes an encoded <code class="typeparamref">TPolyline</code> into a sequence of <code class="typeparamref">TCoordinate</code> instances,
 
     with support for cancellation.
-- code: public IEnumerable<TCoordinate> Decode(TPolyline polyline, CancellationToken cancellationToken)
+- code: public IEnumerable<TCoordinate> Decode(TPolyline polyline, CancellationToken cancellationToken = default)
 - h4: Parameters
 - parameters:
   - name: polyline
@@ -182,6 +145,7 @@ body:
     - text: CancellationToken
       url: https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken
     description: A <xref href="System.Threading.CancellationToken" data-throw-if-not-resolved="false"></xref> that can be used to cancel the decoding operation.
+    optional: true
 - h4: Returns
 - parameters:
   - type:
@@ -203,15 +167,15 @@ body:
     description: Thrown when <code class="paramref">polyline</code> is empty.
   - type:
     - text: InvalidPolylineException
-      url: PolylineAlgorithm.Diagnostics.InvalidPolylineException.html
+      url: PolylineAlgorithm.InvalidPolylineException.html
     description: Thrown when the polyline format is invalid or malformed at a specific position.
   - type:
     - text: OperationCanceledException
       url: https://learn.microsoft.com/dotnet/api/system.operationcanceledexception
     description: Thrown when <code class="paramref">cancellationToken</code> is canceled during decoding.
 - api3: GetReadOnlyMemory(in TPolyline)
   id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2_GetReadOnlyMemory__0__
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L209
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L186
   metadata:
     uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.GetReadOnlyMemory(`0@)
     commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.GetReadOnlyMemory(`0@)
@@ -235,7 +199,7 @@ body:
     description: A <xref href="System.ReadOnlyMemory%601" data-throw-if-not-resolved="false"></xref> of <xref href="System.Char" data-throw-if-not-resolved="false"></xref> representing the encoded polyline characters.
 - api3: ValidateFormat(ReadOnlyMemory<char>, ILogger?)
   id: PolylineAlgorithm_Abstraction_AbstractPolylineDecoder_2_ValidateFormat_System_ReadOnlyMemory_System_Char__Microsoft_Extensions_Logging_ILogger_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L189
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineDecoder.cs#L166
   metadata:
     uid: PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.ValidateFormat(System.ReadOnlyMemory{System.Char},Microsoft.Extensions.Logging.ILogger)
     commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineDecoder`2.ValidateFormat(System.ReadOnlyMemory{System.Char},Microsoft.Extensions.Logging.ILogger)

api-reference/1.0/PolylineAlgorithm.Abstraction.AbstractPolylineEncoder-2.yml

@@ -106,7 +106,7 @@ body:
 - h2: Methods
 - api3: CreatePolyline(ReadOnlyMemory<char>)
   id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2_CreatePolyline_System_ReadOnlyMemory_System_Char__
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L165
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L169
   metadata:
     uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.CreatePolyline(System.ReadOnlyMemory{System.Char})
     commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.CreatePolyline(System.ReadOnlyMemory{System.Char})
@@ -128,17 +128,17 @@ body:
   - type:
     - TPolyline
     description: An instance of <code class="typeparamref">TPolyline</code> representing the encoded polyline.
-- api3: Encode(ReadOnlySpan<TCoordinate>)
-  id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2_Encode_System_ReadOnlySpan__0__
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L76
+- api3: Encode(ReadOnlySpan<TCoordinate>, CancellationToken)
+  id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2_Encode_System_ReadOnlySpan__0__System_Threading_CancellationToken_
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L79
   metadata:
-    uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.Encode(System.ReadOnlySpan{`0})
-    commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.Encode(System.ReadOnlySpan{`0})
+    uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.Encode(System.ReadOnlySpan{`0},System.Threading.CancellationToken)
+    commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.Encode(System.ReadOnlySpan{`0},System.Threading.CancellationToken)
 - markdown: Encodes a collection of <code class="typeparamref">TCoordinate</code> instances into an encoded <code class="typeparamref">TPolyline</code> string.
 - code: >-
     [SuppressMessage("Design", "MA0051:Method is too long", Justification = "Method contains local methods. Actual method only 55 lines.")]
 
-    public TPolyline Encode(ReadOnlySpan<TCoordinate> coordinates)
+    public TPolyline Encode(ReadOnlySpan<TCoordinate> coordinates, CancellationToken cancellationToken = default)
 - h4: Parameters
 - parameters:
   - name: coordinates
@@ -149,6 +149,12 @@ body:
     - TCoordinate
     - '>'
     description: The collection of <code class="typeparamref">TCoordinate</code> objects to encode.
+  - name: cancellationToken
+    type:
+    - text: CancellationToken
+      url: https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken
+    description: A <xref href="System.Threading.CancellationToken" data-throw-if-not-resolved="false"></xref> that can be used to cancel the encoding operation.
+    optional: true
 - h4: Returns
 - parameters:
   - type:
@@ -170,7 +176,7 @@ body:
     description: Thrown when the internal encoding buffer cannot accommodate the encoded value.
 - api3: GetLatitude(TCoordinate)
   id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2_GetLatitude__0_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L185
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L189
   metadata:
     uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.GetLatitude(`0)
     commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.GetLatitude(`0)
@@ -190,7 +196,7 @@ body:
     description: The latitude value as a <xref href="System.Double" data-throw-if-not-resolved="false"></xref>.
 - api3: GetLongitude(TCoordinate)
   id: PolylineAlgorithm_Abstraction_AbstractPolylineEncoder_2_GetLongitude__0_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L175
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/AbstractPolylineEncoder.cs#L179
   metadata:
     uid: PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.GetLongitude(`0)
     commentId: M:PolylineAlgorithm.Abstraction.AbstractPolylineEncoder`2.GetLongitude(`0)

api-reference/1.0/PolylineAlgorithm.Abstraction.IPolylineDecoder-2.yml

@@ -1,9 +1,9 @@
 ### YamlMime:ApiPage
-title: Interface IPolylineDecoder<TPolyline, TCoordinate>
+title: Interface IPolylineDecoder<TPolyline, TValue>
 body:
-- api1: Interface IPolylineDecoder<TPolyline, TCoordinate>
+- api1: Interface IPolylineDecoder<TPolyline, TValue>
   id: PolylineAlgorithm_Abstraction_IPolylineDecoder_2
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/IPolylineDecoder.cs#L13
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/IPolylineDecoder.cs#L22
   metadata:
     uid: PolylineAlgorithm.Abstraction.IPolylineDecoder`2
     commentId: T:PolylineAlgorithm.Abstraction.IPolylineDecoder`2
@@ -15,35 +15,76 @@ body:
   - name: Assembly
     value: PolylineAlgorithm.dll
 - markdown: Defines a contract for decoding an encoded polyline into a sequence of geographic coordinates.
-- code: public interface IPolylineDecoder<TPolyline, out TCoordinate>
+- code: public interface IPolylineDecoder<TPolyline, out TValue>
 - h4: Type Parameters
 - parameters:
   - name: TPolyline
-  - name: TCoordinate
+    description: >-
+      The type that represents the encoded polyline input. Common implementations use <xref href="System.String" data-throw-if-not-resolved="false"></xref>,
+
+      but custom wrapper types are allowed to carry additional metadata.
+  - name: TValue
+    description: >-
+      The coordinate type returned by the decoder. Typical implementations return a struct or class that
+
+      contains latitude and longitude (for example a <code>LatLng</code> type or a <code>ValueTuple&lt;double,double&gt;</code>).
 - h2: Methods
-- api3: Decode(TPolyline)
-  id: PolylineAlgorithm_Abstraction_IPolylineDecoder_2_Decode__0_
-  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/IPolylineDecoder.cs#L23
+- api3: Decode(TPolyline, CancellationToken)
+  id: PolylineAlgorithm_Abstraction_IPolylineDecoder_2_Decode__0_System_Threading_CancellationToken_
+  src: https://github.com/petesramek/polyline-algorithm-csharp/blob/develop/1.0/src/PolylineAlgorithm/Abstraction/IPolylineDecoder.cs#L48
   metadata:
-    uid: PolylineAlgorithm.Abstraction.IPolylineDecoder`2.Decode(`0)
-    commentId: M:PolylineAlgorithm.Abstraction.IPolylineDecoder`2.Decode(`0)
-- markdown: Decodes the specified encoded polyline into a sequence of geographic coordinates.
-- code: IEnumerable<out TCoordinate> Decode(TPolyline polyline)
+    uid: PolylineAlgorithm.Abstraction.IPolylineDecoder`2.Decode(`0,System.Threading.CancellationToken)
+    commentId: M:PolylineAlgorithm.Abstraction.IPolylineDecoder`2.Decode(`0,System.Threading.CancellationToken)
+- markdown: >-
+    Decodes the specified encoded polyline into an ordered sequence of geographic coordinates.
+
+    The sequence preserves the original vertex order encoded by the <code class="paramref">polyline</code>.
+- code: IEnumerable<out TValue> Decode(TPolyline polyline, CancellationToken cancellationToken = default)
 - h4: Parameters
 - parameters:
   - name: polyline
     type:
     - TPolyline
-    description: The <code class="typeparamref">TPolyline</code> instance containing the encoded polyline string to decode.
+    description: >-
+      The <code class="typeparamref">TPolyline</code> instance containing the encoded polyline to decode.
+
+      Implementations SHOULD validate the input and may throw <xref href="System.ArgumentException" data-throw-if-not-resolved="false"></xref>
+
+      or <xref href="System.FormatException" data-throw-if-not-resolved="false"></xref> for invalid formats.
+  - name: cancellationToken
+    type:
+    - text: CancellationToken
+      url: https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken
+    description: >-
+      A <xref href="System.Threading.CancellationToken" data-throw-if-not-resolved="false"></xref> to observe while decoding. If cancellation is requested,
+
+      implementations SHOULD stop work and throw an <xref href="System.OperationCanceledException" data-throw-if-not-resolved="false"></xref>.
+    optional: true
 - h4: Returns
 - parameters:
   - type:
     - text: IEnumerable
       url: https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1
     - <
-    - TCoordinate
+    - TValue
     - '>'
-    description: An <xref href="System.Collections.Generic.IEnumerable%601" data-throw-if-not-resolved="false"></xref> of <code class="typeparamref">TCoordinate</code> representing the decoded latitude and longitude pairs.
+    description: >-
+      An <xref href="System.Collections.Generic.IEnumerable%601" data-throw-if-not-resolved="false"></xref> of <code class="typeparamref">TValue</code> representing the decoded
+
+      latitude/longitude pairs (or equivalent coordinates) in the same order they were encoded.
+- h4: Remarks
+- markdown: >-
+    Implementations commonly follow the Google Encoded Polyline Algorithm Format, but this interface
+
+    does not mandate a specific encoding. Consumers should rely on a concrete decoder's documentation
+
+    to understand the exact encoding supported.
+- h4: Exceptions
+- parameters:
+  - type:
+    - text: OperationCanceledException
+      url: https://learn.microsoft.com/dotnet/api/system.operationcanceledexception
+    description: Thrown when the provided <code class="paramref">cancellationToken</code> requests cancellation.
 languageId: csharp
 metadata:
   description: Defines a contract for decoding an encoded polyline into a sequence of geographic coordinates.