Minor updates (#6)

* Minor updates
* Doc comment updates/clarifications
* Moved GetOrdering to an extension method for IFormatProvider.
* Renamed test namespace for consistency

* minor comment add to re-trigger actions (hopefully)

---------

Co-authored-by: smaillet <25911635+smaillet@users.noreply.github.com>

Author: smaillet

src/Ubiquity.NET.Versioning/AlphaNumericOrdering.cs

@@ -9,7 +9,7 @@ namespace Ubiquity.NET.Versioning
     /// <summary>Identifies the sort ordering expected for a given version</summary>
     public enum AlphaNumericOrdering
     {
-        /// <summary>Indicates no sort ordering</summary>
+        /// <summary>Indicates an invalid sort ordering</summary>
         /// <remarks>
         /// This value is the default for this type and is ALWAYS invalid.
         /// </remarks>

src/Ubiquity.NET.Versioning/AppContextSwitches.cs

@@ -62,6 +62,7 @@ public static bool CSemVerCIOnlySupportsBuildMetaOnZeroTimedVersions
             set => AppContext.SetSwitch(CSemVerCIOnlySupportsBuildMetaOnZeroTimedVersionsName, value);
         }
 
+        // internal utility to read a switch and default to false if not found.
         private static bool GetSwitchValue(string name)
         {
             bool found = AppContext.TryGetSwitch(name, out bool currentVal);

src/Ubiquity.NET.Versioning/CSemVer.cs

@@ -262,6 +262,7 @@ public static CSemVer From( ParsedBuildVersionXml parsedBuildVersionXml, Immutab
         /// <inheritdoc/>
         public static new CSemVer Parse( string s, IFormatProvider? provider )
         {
+            // Throw if provider isn't one that is ignorable.
             provider.ThrowIfCaseSensitive();
             return TryParse( s, out CSemVer? retVal, out Exception? ex ) ? retVal : throw ex;
         }
@@ -272,6 +273,7 @@ public static CSemVer From( ParsedBuildVersionXml parsedBuildVersionXml, Immutab
         /// </remarks>
         public static bool TryParse( [NotNullWhen( true )] string? s, IFormatProvider? provider, [MaybeNullWhen( false )] out CSemVer result )
         {
+            // Throw if provider isn't one that is ignorable.
             provider.ThrowIfCaseSensitive();
             return TryParse( s, out result, out _ );
         }

src/Ubiquity.NET.Versioning/CSemVerCI.cs

@@ -214,13 +214,15 @@ public static bool TryFrom(
         /// <inheritdoc/>
         public static new CSemVerCI Parse( string s, IFormatProvider? provider )
         {
+            // Throw if provider isn't one that is ignorable.
             provider.ThrowIfCaseSensitive();
             return TryParse( s, out CSemVerCI? retVal, out Exception? ex ) ? retVal : throw ex;
         }
 
         /// <inheritdoc/>
         public static bool TryParse( [NotNullWhen( true )] string? s, IFormatProvider? provider, [MaybeNullWhen( false )] out CSemVerCI result )
         {
+            // Throw if provider isn't one that is ignorable.
             provider.ThrowIfCaseSensitive();
             return TryParse( s, out result, out _ );
         }

src/Ubiquity.NET.Versioning/FormatProviderExtensions.cs

@@ -25,5 +25,12 @@ public static void ThrowIfCaseSensitive(this IFormatProvider? provider, [CallerA
                 throw new ArgumentException("Format provider must be <null> or provide a CaseInsensitive comparison", exp);
             }
         }
+
+        public static AlphaNumericOrdering GetOrdering(this IFormatProvider provider)
+        {
+            ArgumentNullException.ThrowIfNull(provider);
+
+            return (AlphaNumericOrdering?)provider.GetFormat(typeof(AlphaNumericOrdering)) ?? AlphaNumericOrdering.None;
+        }
     }
 }

src/Ubiquity.NET.Versioning/PackageReadMe.md

@@ -43,15 +43,18 @@ sort ordering of the versions according to the rules of SemVer (Which, CSemVer a
 follow with the exception of explicit case insensitivity for AphaNumeric IDs)
 
 >[!WARNING]
-> The formal 'spec' for [CSemVer](https://csemver.org) remains mostly silent on the point of
-> the short format. See this [known issue](https://github.com/CK-Build/csemver.org/issues/2).
+> The formal 'spec' for [CSemVer](https://csemver.org) remains mostly silent on the point
+> of the short format. See this [known issue](https://github.com/CK-Build/csemver.org/issues/2).
 > Since, the existence of that form was to support NuGet V2, which is now obsolete, this
 > library does not support the short form at all. (This choice keeps documentation clarity
 > [NOT SUPPORTED] and implementation simplicity)
 
 ------
-<sup><a id="footnote_1">1</a></sup> `SemVer` contains constructors accepting an
-`AlhpanumericOrdering` enumeration to identify the ordering expected for a given instance.
-Unfortunately, major repositories using SemVer have chosen to use different comparisons. Thus,
-a consumer is required to specify if the version is compared insensitive or not.
-
+<sup><a id="footnote_1">1</a></sup>Unfortunately, major repositories using SemVer have
+chosen to use different comparisons. Thus, a consumer is required to know a-priori if the
+version is compared insensitive or not. Thus all constructors accept an enum indicating
+the sort ordering to use. Additional, parsing accepts an IFormatProvider, which should
+provide an `AlphaNumeirvOrdering` value to specify the ordering. If none is provided, the
+default is used. (SemVer uses CaseSensitive comparisons, CSemVer and CSemVerCI ALWAYS use
+case insensitive) `IComparer<SemVer>` instances are available for cases where the versions
+are from mixed sources and the application wishes to order the versions.

src/Ubiquity.NET.Versioning/SemVer.cs

@@ -278,7 +278,7 @@ internal static bool TryParse(
             ArgumentNullException.ThrowIfNull( s );
 
             provider ??= SemVerFormatProvider.CaseSensitive;
-            IResult<SemVer> parseResult = SemVerGrammar.SemanticVersion(GetOrdering(provider)).TryParse(s);
+            IResult<SemVer> parseResult = SemVerGrammar.SemanticVersion(provider.GetOrdering()).TryParse(s);
             if(parseResult.Failed(out ex))
             {
                 result = default;
@@ -364,10 +364,5 @@ private static ImmutableArray<string> ValidateElementsWithParser(
 
             return value.Value;
         }
-
-        private static AlphaNumericOrdering GetOrdering(IFormatProvider? provider)
-        {
-            return (AlphaNumericOrdering?)provider?.GetFormat(typeof(AlphaNumericOrdering)) ?? AlphaNumericOrdering.None;
-        }
     }
 }