Clarify INumber.IsPositive and INumber.IsNegative documentation (#80026)

* Clarify INumber.IsPositive and INumber.IsNegative documentation

* Add clarification for negative zero

diff --git a/src/libraries/System.Private.CoreLib/src/System/Numerics/INumberBase.cs b/src/libraries/System.Private.CoreLib/src/System/Numerics/INumberBase.cs
index 90f1d2d..0040a88 100644 (file)
--- a/src/libraries/System.Private.CoreLib/src/System/Numerics/INumberBase.cs
+++ b/src/libraries/System.Private.CoreLib/src/System/Numerics/INumberBase.cs
@@ -166,10 +166,13 @@ namespace System.Numerics
         /// <returns><c>true</c> if <paramref name="value" /> is NaN; otherwise, <c>false</c>.</returns>
         static abstract bool IsNaN(TSelf value);
 
-        /// <summary>Determines if a value is negative.</summary>
+        /// <summary>Determines if a value represents a negative real number.</summary>
         /// <param name="value">The value to be checked.</param>
-        /// <returns><c>true</c> if <paramref name="value" /> is negative; otherwise, <c>false</c>.</returns>
-        /// <remarks>This function returning <c>false</c> does not imply that <see cref="IsPositive(TSelf)" /> will return <c>true</c>. A complex number, <c>a + bi</c> for non-zero <c>b</c>, is not positive nor negative</remarks>
+        /// <returns><c>true</c> if <paramref name="value" /> represents negative zero or a negative real number; otherwise, <c>false</c>.</returns>
+        /// <remarks>
+        ///     <para>If this type has signed zero, then <c>-0</c> is also considered negative.</para>
+        ///     <para>This function returning <c>false</c> does not imply that <see cref="IsPositive(TSelf)" /> will return <c>true</c>. A complex number, <c>a + bi</c> for non-zero <c>b</c>, is not positive nor negative</para>
+        /// </remarks>
         static abstract bool IsNegative(TSelf value);
 
         /// <summary>Determines if a value is negative infinity.</summary>
@@ -191,10 +194,13 @@ namespace System.Numerics
         /// </remarks>
         static abstract bool IsOddInteger(TSelf value);
 
-        /// <summary>Determines if a value is positive.</summary>
+        /// <summary>Determines if a value represents zero or a positive real number.</summary>
         /// <param name="value">The value to be checked.</param>
-        /// <returns><c>true</c> if <paramref name="value" /> is positive; otherwise, <c>false</c>.</returns>
-        /// <remarks>This function returning <c>false</c> does not imply that <see cref="IsNegative(TSelf)" /> will return <c>true</c>. A complex number, <c>a + bi</c> for non-zero <c>b</c>, is not positive nor negative</remarks>
+        /// <returns><c>true</c> if <paramref name="value" /> represents (positive) zero or a positive real number; otherwise, <c>false</c>.</returns>
+        /// <remarks>
+        ///     <para>If this type has signed zero, then <c>-0</c> is not considered positive, but <c>+0</c> is.</para>
+        ///     <para>This function returning <c>false</c> does not imply that <see cref="IsNegative(TSelf)" /> will return <c>true</c>. A complex number, <c>a + bi</c> for non-zero <c>b</c>, is not positive nor negative</para>
+        /// </remarks>
         static abstract bool IsPositive(TSelf value);
 
         /// <summary>Determines if a value is positive infinity.</summary>