Add NotNullWhen attribute to TryGetCountry overload

Introduced conditional overloads of TryGetCountry in ICountryProvider and CountryProvider for .NET Standard 2.1+ and .NET Core 3.0+, using [NotNullWhen(true)] for improved nullability annotations. Updated XML documentation for interface methods to clarify parameters, return values, and exceptions.

Author: tinohager

src/Nager.Country/CountryProvider.cs

@@ -2,6 +2,10 @@
 using System;
 using System.Collections.Generic;
 
+#if NETSTANDARD2_1_OR_GREATER || NETCOREAPP3_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+#endif
+
 namespace Nager.Country
 {
     /// <summary>
@@ -304,6 +308,8 @@ public ICountryInfo GetCountry(string alpha2or3Code)
             throw new UnknownCountryException($"Cannot found a country for code {alpha2or3Code}");
         }
 
+#if NETSTANDARD2_0 || NET48
+
         /// <inheritdoc/>
         public bool TryGetCountry(string alpha2or3Code, out ICountryInfo? countryInfo)
         {
@@ -323,6 +329,31 @@ public bool TryGetCountry(string alpha2or3Code, out ICountryInfo? countryInfo)
             return false;
         }
 
+#endif
+
+#if NETSTANDARD2_1_OR_GREATER || NETCOREAPP3_0_OR_GREATER
+
+        /// <inheritdoc/>
+        public bool TryGetCountry(string alpha2or3Code, [NotNullWhen(true)] out ICountryInfo? countryInfo)
+        {
+            if (Enum.TryParse(alpha2or3Code, true, out Alpha2Code alpha2Code))
+            {
+                countryInfo = this.GetCountry(alpha2Code);
+                return true;
+            }
+
+            if (Enum.TryParse(alpha2or3Code, true, out Alpha3Code alpha3Code))
+            {
+                countryInfo = this.GetCountry(alpha3Code);
+                return true;
+            }
+
+            countryInfo = null;
+            return false;
+        }
+
+#endif
+
         /// <inheritdoc/>
         public ICountryInfo GetCountry(Alpha2Code alpha2Code)
         {

src/Nager.Country/ICountryProvider.cs

@@ -1,45 +1,78 @@
 using System.Collections.Generic;
 
+#if NETSTANDARD2_1_OR_GREATER || NETCOREAPP3_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+#endif
+
 namespace Nager.Country
 {
     /// <summary>
-    /// ICountryProvider
+    /// CountryProvider Interface
     /// </summary>
     public interface ICountryProvider
     {
         /// <summary>
-        /// Get all country informations
+        /// Retrieves information for all available countries.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>An <see cref="IEnumerable{ICountryInfo}"/> containing all country information.</returns>
         IEnumerable<ICountryInfo> GetCountries();
 
         /// <summary>
-        /// Get country by alpha2 or alpha3 code
+        /// Retrieves information for a specific country by its ISO alpha-2 or alpha-3 code.
         /// </summary>
-        /// <param name="alpha2or3Code"></param>
-        /// <returns></returns>
+        /// <param name="alpha2or3Code">The ISO alpha-2 or alpha-3 code of the country.</param>
+        /// <returns>The <see cref="ICountryInfo"/> corresponding to the specified code.</returns>
+        /// <exception cref="UnknownCountryException">Thrown if no country matches the provided code.</exception>
         ICountryInfo GetCountry(string alpha2or3Code);
 
+#if NETSTANDARD2_0 || NET48
+
         /// <summary>
-        /// Try get country by alpha2 or alpha3 code
+        /// Attempts to retrieve country information by its ISO alpha-2 or alpha-3 code.
         /// </summary>
-        /// <param name="alpha2or3Code"></param>
-        /// <param name="countryInfo"></param>
-        /// <returns></returns>
+        /// <param name="alpha2or3Code">The ISO alpha-2 or alpha-3 code of the country.</param>
+        /// <param name="countryInfo">
+        /// When this method returns, contains the <see cref="ICountryInfo"/> 
+        /// for the specified code if found; otherwise, null.
+        /// </param>
+        /// <returns>
+        /// <c>true</c> if a country matching the specified code was found; otherwise, <c>false</c>.
+        /// </returns>
         bool TryGetCountry(string alpha2or3Code, out ICountryInfo? countryInfo);
 
+#endif
+
+#if NETSTANDARD2_1_OR_GREATER || NETCOREAPP3_0_OR_GREATER
+
+        /// <summary>
+        /// Attempts to retrieve country information by its ISO alpha-2 or alpha-3 code.
+        /// </summary>
+        /// <param name="alpha2or3Code">The ISO alpha-2 or alpha-3 code of the country.</param>
+        /// <param name="countryInfo">
+        /// When this method returns, contains the <see cref="ICountryInfo"/> 
+        /// for the specified code if found; otherwise, null.
+        /// </param>
+        /// <returns>
+        /// <c>true</c> if a country matching the specified code was found; otherwise, <c>false</c>.
+        /// </returns>
+        bool TryGetCountry(string alpha2or3Code, [NotNullWhen(true)] out ICountryInfo? countryInfo);
+
+#endif
+
         /// <summary>
-        /// Get country by alpha2 code
+        /// Retrieves information about a country using its ISO 3166-1 alpha-2 code.
         /// </summary>
-        /// <param name="alpha2Code"></param>
-        /// <returns></returns>
+        /// <param name="alpha2Code">The ISO alpha-2 code of the country.</param>
+        /// <returns>The <see cref="ICountryInfo"/> corresponding to the specified code.</returns>
+        /// <exception cref="UnknownCountryException">Thrown if no country matches the provided code.</exception>
         ICountryInfo GetCountry(Alpha2Code alpha2Code);
 
         /// <summary>
-        /// Get country by alpha3 code
+        /// Retrieves information about a country using its ISO 3166-1 alpha-3 code.
         /// </summary>
-        /// <param name="alpha3Code"></param>
-        /// <returns></returns>
+        /// <param name="alpha3Code">The ISO alpha-3 code of the country.</param>
+        /// <returns>The <see cref="ICountryInfo"/> corresponding to the specified code.</returns>
+        /// <exception cref="UnknownCountryException">Thrown if no country matches the provided code.</exception>
         ICountryInfo GetCountry(Alpha3Code alpha3Code);
 
         /// <summary>
@@ -50,7 +83,8 @@ public interface ICountryProvider
         /// GetCountryByNameConsiderTranslation -> <see href="https://github.com/nager/Nager.Country/blob/master/src/Nager.Country.Translation/CountryProviderExtension.cs>">CountryProviderExtension</see>
         /// </remarks>
         /// <param name="countryName"></param>
-        /// <returns></returns>
+        /// <returns>The <see cref="ICountryInfo"/> corresponding to the specified code.</returns>
+        /// <exception cref="UnknownCountryException">Thrown if no country matches the provided code.</exception>
         ICountryInfo GetCountryByName(string countryName);
     }
 }