More doc updates

docfx/index.md

@@ -14,14 +14,14 @@ while conforming to the syntax of CSemVer and CSemVer-CI
 > There is confusion on the ordering of a CI build with relation to a release build with
 > CSemVer-CI. A CI Build is either an initial build of an unreleased version with
 > [Major.Minor.Patch] == [0.0.0]. Or, it is based on the previously released version and
-is [Major.Minor.Patch+1]. That is, a CI build is ordered BEFORE all release builds, or it
-> is ordered AFTER the specific release it is based on! In particular a CI build version
-> does ***NOT*** indicate what it will become when it is finally released, but what
-> release it was based on (If any). To simplify that, for clarity, a CI build contains
-> everything in the release it was based on and additional changes (that might remove
-> things). CI builds are, by definition NOT stable and consumers cannot rely on them for
-> predictions of future stability. A given CI build may even represent an abandoned
-> approach that never becomes a release!
+> is [Major.Minor.Patch+1]. That is, a CI build is ordered ***BEFORE*** all release builds,
+> or it is ordered ***AFTER*** the ***specific*** release it is based on! In particular a
+> CI build version does ***NOT*** indicate what it will become when it is finally released,
+> but what release it was based on (If any). To simplify that, for clarity, a CI build
+> contains everything in the release it was based on and additional changes (that might
+> remove things). CI builds are, by definition NOT stable and consumers cannot rely on
+> them for predictions of future stability. A given CI build may even represent an
+> abandoned approach that never becomes a release!
 
 ---
 [Attributions](Attributions.md)

src/Ubiquity.NET.Versioning/AppContextSwitches.cs

@@ -49,15 +49,12 @@ public const string CSemVerCIOnlySupportsBuildMetaOnZeroTimedVersionsName
         /// <para>The spec is vague on the precise syntax of a CSemVer-CI value and whether a given form can include build meta data.
         /// It is at least explicitly allowed for ZeroTimed base values. But it is unclear if it is supposed to be allowed
         /// for any "latest release" forms. Sadly, .NET builds using SourceLink will automatically add the build meta if not present
-        /// so this implementation choses to assume that is legit. This seems reasonable as the build meta doesn't participate
-        /// in the ordering of version values and is syntactically compatible with both forms of CSemVer-CI. That is the default behavior
+        /// so this implementation chooses to assume that is legit. This seems reasonable as the build meta doesn't participate
+        /// in the ordering of version values and is syntactically compatible with both forms of CSemVer-CI. That is, the default behavior
         /// of allowing it has low risk of causing problems, but the reverse can.</para>
         /// <para>As with all <see cref="AppContext"/> switches the default state of this switch is OFF. Setting it ON, is a manual operation
         /// that may use one of the standard mechanisms supported by <see cref="AppContext"/> using this name. Or, programmatically via the
         /// <see cref="CSemVerCIOnlySupportsBuildMetaOnZeroTimedVersions"/>.</para>
-        /// <para>For `app.config` and other <see cref="AppContext"/> uses, the name is formally documented as
-        /// "Ubiquity.NET.Versioning.AppContextSwitches.CSemVerCIOnlySupportsBuildMetaOnZeroTimedVersions".
-        /// </para>
         /// </remarks>
         public static bool CSemVerCIOnlySupportsBuildMetaOnZeroTimedVersions
         {

src/Ubiquity.NET.Versioning/CSemVer.cs

@@ -30,12 +30,7 @@ public readonly struct CSemVer
         /// <param name="minor">Minor version value [0-49999]</param>
         /// <param name="patch">Patch version value [0-9999]</param>
         /// <param name="preRelVersion">Pre-release version information (if a pre-release build)</param>
-        /// <param name="buildMetaData">[Optional]Additional build meta data [default: empty string]</param>
-        /// <remarks>
-        /// This is used internally when converting from a File Version as those only have a single bit
-        /// to indicate if they are a Release/CI build. The rest of the information is lost and therefore
-        /// does not participate in ordering.
-        /// </remarks>
+        /// <param name="buildMetaData">Any additional build meta data [default: empty string]</param>
         public CSemVer( int major
                       , int minor
                       , int patch
@@ -77,8 +72,10 @@ public CSemVer( int major
         /// <summary>Gets the <see cref="FileVersionQuad"/> representation of this <see cref="CSemVer"/></summary>
         /// <remarks>
         /// Since a <see cref="FileVersionQuad"/> is entirely numeric the conversion is somewhat "lossy" but does
-        /// NOT lose any relation to other versions converted. That, is the loss does not include any information
-        /// that impacts build version sort ordering. (any data lost is ignored for sort ordering anyway)
+        /// NOT lose any relation to other released versions converted. That, is the loss does not include any CI
+        /// information, only that it was a CI build. Two CI builds with the same base version will produce the
+        /// same value! CI builds are not intended for long term stability and this is not a bug but a design of
+        /// how CSemVer (and CSemVer-CI) work to produce a <see cref="FileVersionQuad"/>.
         /// </remarks>
         public FileVersionQuad FileVersion
         {
@@ -119,7 +116,8 @@ public ulong OrderedVersion
         /// <summary>Gets a value indicating whether this is a zero based version</summary>
         public bool IsZero => Major == 0 && Minor == 0 && Patch == 0;
 
-        /// <inheritdoc/>
+        /// <summary>Converts the internal representation of this version to a valid CSemVer formatted string</summary>
+        /// <returns>CSemVer formatted string</returns>
         public override string ToString( )
         {
             return ConstrainedVersion?.ToString() ?? string.Empty;
@@ -183,9 +181,9 @@ public override int GetHashCode( )
         /// <returns><see langword="true"/> if the conversion is performed or <see langword="false"/> if not (<paramref name="reason"/> will hold reason it is not successful)</returns>
         /// <remarks>
         /// While EVERY <see cref="CSemVer"/> conforms to valid <see cref="SemVer"/> the reverse is not always true.
-        /// This method attempts to make a conversion using the classic try pattern with the inclusion of a string
+        /// This method attempts to make a conversion using the classic try pattern with the inclusion of an exception
         /// that explains the reason for any failures. This is useful in debugging or for creating wrappers that will
-        /// throw an exception.
+        /// throw the exception.
         /// </remarks>
         public static bool TryFrom(
             SemVer ver,
@@ -273,7 +271,7 @@ public static CSemVer From( UInt64 fileVersion, IReadOnlyCollection<string>? bui
         /// <summary>Converts a CSemVer ordered version integral value (UInt64) into a full <see cref="CSemVer"/></summary>
         /// <param name="orderedVersion">The ordered version value</param>
         /// <param name="buildMetaData">Optional build meta data value for the version</param>
-        /// <returns><see cref="CSemVer"/> corresponding to the ordered version number provided</returns>
+        /// <returns>Version corresponding to the ordered version number provided</returns>
         public static CSemVer FromOrderedVersion( UInt64 orderedVersion, IReadOnlyCollection<string>? buildMetaData = null )
         {
             buildMetaData ??= [];
@@ -314,7 +312,7 @@ public static CSemVer FromOrderedVersion( UInt64 orderedVersion, IReadOnlyCollec
         /// <summary>Factory method to create a <see cref="CSemVer"/> from information available as part of a build</summary>
         /// <param name="buildVersionXmlPath">Path to the BuildVersion XML data for the repository</param>
         /// <param name="buildMeta">Additional Build meta data for the build</param>
-        /// <returns><see cref="CSemVer"/></returns>
+        /// <returns>Version information parsed from the build XML</returns>
         public static CSemVer From( string buildVersionXmlPath, IReadOnlyCollection<string>? buildMeta )
         {
             var parsedBuildVersionXml = ParsedBuildVersionXml.ParseFile( buildVersionXmlPath );
@@ -343,6 +341,9 @@ public static CSemVer Parse( string s, IFormatProvider? provider )
         }
 
         /// <inheritdoc/>
+        /// <remarks>
+        /// <paramref name="provider"/> is ALWAYS ignored by this implementation. The format is defined by the spec and independent of culture.
+        /// </remarks>
         public static bool TryParse( [NotNullWhen( true )] string? s, IFormatProvider? provider, [MaybeNullWhen( false )] out CSemVer result )
         {
             return TryParse(s, out result, out _);