From ab6cf45b03073f324c46f9e93a98e3342a1bdff7 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <Pathoschild@users.noreply.github.com>
Date: Thu, 7 Apr 2022 00:56:00 -0400
Subject: enable nullable annotations for semantic versions (#837)

---
 .../ISemanticVersion.cs                            | 38 ++++++++++++----------
 1 file changed, 21 insertions(+), 17 deletions(-)

(limited to 'src/SMAPI.Toolkit.CoreInterfaces')

diff --git a/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs b/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs
index 52cec52e..7998272f 100644
--- a/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs
+++ b/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs
@@ -1,5 +1,3 @@
-#nullable disable
-
 using System;
 
 namespace StardewModdingAPI
@@ -20,10 +18,10 @@ namespace StardewModdingAPI
         int PatchVersion { get; }
 
         /// <summary>An optional prerelease tag.</summary>
-        string PrereleaseTag { get; }
+        string? PrereleaseTag { get; }
 
         /// <summary>Optional build metadata. This is ignored when determining version precedence.</summary>
-        string BuildMetadata { get; }
+        string? BuildMetadata { get; }
 
 
         /*********
@@ -34,32 +32,38 @@ namespace StardewModdingAPI
 
         /// <summary>Get whether this version is older than the specified version.</summary>
         /// <param name="other">The version to compare with this instance.</param>
-        bool IsOlderThan(ISemanticVersion other);
+        /// <remarks>Although the <paramref name="other"/> parameter is nullable, it isn't optional. A <c>null</c> version is considered earlier than every possible valid version, so passing <c>null</c> to <paramref name="other"/> will always return false.</remarks>
+        bool IsOlderThan(ISemanticVersion? other);
 
         /// <summary>Get whether this version is older than the specified version.</summary>
-        /// <param name="other">The version to compare with this instance.</param>
+        /// <param name="other">The version to compare with this instance.  A null value is never older.</param>
         /// <exception cref="FormatException">The specified version is not a valid semantic version.</exception>
-        bool IsOlderThan(string other);
+        /// <remarks>Although the <paramref name="other"/> parameter is nullable, it isn't optional. A <c>null</c> version is considered earlier than every possible valid version, so passing <c>null</c> to <paramref name="other"/> will always return false.</remarks>
+        bool IsOlderThan(string? other);
 
         /// <summary>Get whether this version is newer than the specified version.</summary>
-        /// <param name="other">The version to compare with this instance.</param>
-        bool IsNewerThan(ISemanticVersion other);
+        /// <param name="other">The version to compare with this instance. A null value is always older.</param>
+        /// <remarks>Although the <paramref name="other"/> parameter is nullable, it isn't optional. A <c>null</c> version is considered earlier than every possible valid version, so passing <c>null</c> to <paramref name="other"/> will always return true.</remarks>
+        bool IsNewerThan(ISemanticVersion? other);
 
         /// <summary>Get whether this version is newer than the specified version.</summary>
-        /// <param name="other">The version to compare with this instance.</param>
+        /// <param name="other">The version to compare with this instance. A null value is always older.</param>
         /// <exception cref="FormatException">The specified version is not a valid semantic version.</exception>
-        bool IsNewerThan(string other);
+        /// <remarks>Although the <paramref name="other"/> parameter is nullable, it isn't optional. A <c>null</c> version is considered earlier than every possible valid version, so passing <c>null</c> to <paramref name="other"/> will always return true.</remarks>
+        bool IsNewerThan(string? other);
 
         /// <summary>Get whether this version is between two specified versions (inclusively).</summary>
-        /// <param name="min">The minimum version.</param>
-        /// <param name="max">The maximum version.</param>
-        bool IsBetween(ISemanticVersion min, ISemanticVersion max);
+        /// <param name="min">The minimum version. A null value is always older.</param>
+        /// <param name="max">The maximum version. A null value is never newer.</param>
+        /// <remarks>Although the <paramref name="min"/> and <paramref name="max"/> parameters are nullable, they are not optional. A <c>null</c> version is considered earlier than every possible valid version. For example, passing <c>null</c> to <paramref name="max"/> will always return false, since no valid version can be earlier than <c>null</c>.</remarks>
+        bool IsBetween(ISemanticVersion? min, ISemanticVersion? max);
 
         /// <summary>Get whether this version is between two specified versions (inclusively).</summary>
-        /// <param name="min">The minimum version.</param>
-        /// <param name="max">The maximum version.</param>
+        /// <param name="min">The minimum version. A null value is always older.</param>
+        /// <param name="max">The maximum version. A null value is never newer.</param>
         /// <exception cref="FormatException">One of the specified versions is not a valid semantic version.</exception>
-        bool IsBetween(string min, string max);
+        /// <remarks>Although the <paramref name="min"/> and <paramref name="max"/> parameters are nullable, they are not optional. A <c>null</c> version is considered earlier than every possible valid version. For example, passing <c>null</c> to <paramref name="max"/> will always return false, since no valid version can be earlier than <c>null</c>.</remarks>
+        bool IsBetween(string? min, string? max);
 
         /// <summary>Get a string representation of the version.</summary>
         string ToString();
-- 
cgit