From 4124b7cc8a6e659e7ce6c8909d5c316b5eb7aeb2 Mon Sep 17 00:00:00 2001
From: Dave Transom <dave.transom@gmail.com>
Date: Fri, 8 May 2020 15:10:43 +1200
Subject: [PATCH] Documentation improvements, version bump

---
 .../CSharpVitamins.ShortGuid.csproj           |  7 ++--
 CSharpVitamins.ShortGuid/ShortGuid.cs         | 40 ++++++++++---------
 2 files changed, 26 insertions(+), 21 deletions(-)

diff --git a/CSharpVitamins.ShortGuid/CSharpVitamins.ShortGuid.csproj b/CSharpVitamins.ShortGuid/CSharpVitamins.ShortGuid.csproj
index 1532bed..6391663 100644
--- a/CSharpVitamins.ShortGuid/CSharpVitamins.ShortGuid.csproj
+++ b/CSharpVitamins.ShortGuid/CSharpVitamins.ShortGuid.csproj
@@ -6,16 +6,17 @@
     <RootNamespace>CSharpVitamins</RootNamespace>
     <Authors>Dave Transom</Authors>
     <Company>CSharpVitamins</Company>
-    <Description>A convenience wrapper struct for dealing with URL-safe base64 encoded globally unique identifier (GUID), making a shorter string value (22 vs 36 characters long).</Description>
+    <Description>A convenience wrapper struct for dealing with URL-safe Base64 encoded globally unique identifiers (GUID), making a shorter string value (22 vs 36 characters long).</Description>
     <PackageLicenseFile>LICENSE.md</PackageLicenseFile>
     <PackageProjectUrl>https://github.com/csharpvitamins/csharpvitamins.shortguid/</PackageProjectUrl>
     <PackageLicenseExpression></PackageLicenseExpression>
     <RepositoryUrl>https://github.com/csharpvitamins/csharpvitamins.shortguid/</RepositoryUrl>
     <PackageTags>Guid ShortGuid Identifiers Base64</PackageTags>
-    <PackageReleaseNotes>- 1.0.1 Target netstandard2.0 and net40
+    <PackageReleaseNotes>- 1.0.2 Fix: Ambiguous use of `==` operator when comparing Guid and ShortGuid instances
+- 1.0.1 Target netstandard2.0 and net40
 - 1.0.0 Initial release</PackageReleaseNotes>
     <Copyright>Copyright 2007</Copyright>
-    <Version>1.0.1</Version>
+    <Version>1.0.2</Version>
   </PropertyGroup>
 
   <ItemGroup>
diff --git a/CSharpVitamins.ShortGuid/ShortGuid.cs b/CSharpVitamins.ShortGuid/ShortGuid.cs
index 209ffa9..4d415e8 100644
--- a/CSharpVitamins.ShortGuid/ShortGuid.cs
+++ b/CSharpVitamins.ShortGuid/ShortGuid.cs
@@ -4,17 +4,19 @@
 namespace CSharpVitamins
 {
     /// <summary>
-    /// A convenience wrapper struct for dealing with URL-safe Base64 encoded globally unique identifier (GUID),
+    /// A convenience wrapper struct for dealing with URL-safe Base64 encoded globally unique identifiers (GUID),
     /// making a shorter string value (22 vs 36 characters long).
     /// </summary>
     /// <remarks>
-    /// URL-safe Base64? That's just a Base64 string with well known special characters replaced (/, +) or removed (==).
+    /// What is URL-safe Base64? That's just a Base64 string with well known special characters replaced (/, +)
+    /// or removed (==).
     /// </remarks>
     [DebuggerDisplay("{Value}")]
     public struct ShortGuid
     {
         /// <summary>
-        /// A read-only instance of the ShortGuid struct whose value is guaranteed to be all zeroes.
+        /// A read-only instance of the ShortGuid struct whose value is guaranteed to be all zeroes i.e. equivilent
+        /// to <see cref="Guid.Empty"/>.
         /// </summary>
         public static readonly ShortGuid Empty = new ShortGuid(Guid.Empty);
 
@@ -22,10 +24,11 @@ public struct ShortGuid
         string encodedString;
 
         /// <summary>
-        /// Creates a new instance with the given Base64 encoded string.
-        /// (See also <seealso cref="ShortGuid.TryParse(string, out ShortGuid)"/>)
+        /// Creates a new instance with the given URL-safe Base64 encoded string.
+        /// See also <seealso cref="ShortGuid.TryParse(string, out ShortGuid)"/> which will try to coerce the
+        /// the value from URL-safe Base64 or normal Guid string
         /// </summary>
-        /// <param name="value">A ShortGuid encoded string.</param>
+        /// <param name="value">A ShortGuid encoded string e.g. URL-safe Base64.</param>
         public ShortGuid(string value)
         {
             encodedString = value;
@@ -33,7 +36,7 @@ public ShortGuid(string value)
         }
 
         /// <summary>
-        /// Creates a new instance with the given Guid.
+        /// Creates a new instance with the given <see cref="Guid"/>.
         /// </summary>
         /// <param name="guid">The Guid to encode.</param>
         public ShortGuid(Guid guid)
@@ -43,17 +46,17 @@ public ShortGuid(Guid guid)
         }
 
         /// <summary>
-        /// Gets the underlying Guid for the encoded ShortGuid.
+        /// Gets the underlying <see cref="Guid"/> for the encoded ShortGuid.
         /// </summary>
         public Guid Guid => underlyingGuid;
 
         /// <summary>
-        /// Gets the encoded string value of the Guid.
+        /// Gets the encoded string value of the <see cref="Guid"/> i.e. a URL-safe Base64 string.
         /// </summary>
         public string Value => encodedString;
 
         /// <summary>
-        /// Returns the encoded string value.
+        /// Returns the encoded URL-safe Base64 string.
         /// </summary>
         /// <returns></returns>
         public override string ToString() => encodedString;
@@ -91,7 +94,7 @@ public override bool Equals(object obj)
         }
 
         /// <summary>
-        /// Returns the HashCode for the underlying Guid.
+        /// Returns the hash code for the underlying <see cref="Guid"/>.
         /// </summary>
         /// <returns></returns>
         public override int GetHashCode() => underlyingGuid.GetHashCode();
@@ -107,7 +110,7 @@ public override bool Equals(object obj)
         /// Base64, with some non-URL safe characters replaced, and padding removed.
         /// </summary>
         /// <param name="value">Any valid <see cref="Guid"/> string.</param>
-        /// <returns>A 22 character ShortGuid string.</returns>
+        /// <returns>A 22 character ShortGuid URL-safe Base64 string.</returns>
         public static string Encode(string value)
         {
             var guid = new Guid(value);
@@ -119,7 +122,7 @@ public static string Encode(string value)
         /// Base64, with some non-URL safe characters replaced, and padding removed.
         /// </summary>
         /// <param name="guid">The <see cref="Guid"/> to encode.</param>
-        /// <returns>A 22 character ShortGuid string.</returns>
+        /// <returns>A 22 character ShortGuid URL-safe Base64 string.</returns>
         public static string Encode(Guid guid)
         {
             string encoded = Convert.ToBase64String(guid.ToByteArray());
@@ -218,7 +221,7 @@ public static bool TryDecode(string value, out Guid guid)
         public static implicit operator string(ShortGuid shortGuid) => shortGuid.encodedString;
 
         /// <summary>
-        /// Implicitly converts the ShortGuid to its Guid equivalent.
+        /// Implicitly converts the ShortGuid to its <see cref="Guid"/> equivalent.
         /// </summary>
         public static implicit operator Guid(ShortGuid shortGuid) => shortGuid.underlyingGuid;
 
@@ -233,11 +236,12 @@ public static implicit operator ShortGuid(string value)
             if (TryParse(value, out ShortGuid shortGuid))
                 return shortGuid;
 
-            throw new FormatException("ShortGuid should contain 22 Base64 characters or Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).");
+            throw new FormatException("ShortGuid should contain 22 Base64 characters or "
+                + "Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).");
         }
 
         /// <summary>
-        /// Implicitly converts the Guid to a ShortGuid.
+        /// Implicitly converts the <see cref="Guid"/> to a ShortGuid.
         /// </summary>
         public static implicit operator ShortGuid(Guid guid)
         {
@@ -250,7 +254,7 @@ public static implicit operator ShortGuid(Guid guid)
         #endregion
 
         /// <summary>
-        /// Tries to parse the value as a ShortGuid or Guid string.
+        /// Tries to parse the value as a ShortGuid or <see cref="Guid"/> string.
         /// </summary>
         /// <param name="value">The ShortGuid encoded string or string representation of a Guid.</param>
         /// <param name="shortGuid">A new <see cref="ShortGuid"/> instance from the parsed string.</param>
@@ -276,7 +280,7 @@ public static bool TryParse(string value, out ShortGuid shortGuid)
         }
 
         /// <summary>
-        /// Tries to parse the value as a ShortGuid or Guid string, and outputs the underlying Guid value.
+        /// Tries to parse the value as a ShortGuid or <see cref="Guid"/> string, and outputs the underlying <see cref="Guid"/> value.
         /// </summary>
         /// <param name="value">The ShortGuid encoded string or string representation of a Guid.</param>
         /// <param name="guid">A new <see cref="Guid"/> instance from the parsed string.</param>