Make note on change from previous behavior (#3766)

* Added IEE 754 compliance note to TryParse & Parse

* Update description to match @tannergooding's description (with tweaks from @gewarren)

* Tweak the description of System.Double

Credits to @gewarren

Co-Authored-By: Genevieve Warren <[email protected]>

* Remove accidental modifications to closing tags of markdown xref elements.

* Correct accidental formatting change

Misplaced an opening CDATA on a newline, whereas the current style appears to have it stay on the same line.

* Use <see cref=> tags instead of <xref: in an XML context.

Author: SirJosh3917

xml/System/Double.xml

@@ -64,7 +64,7 @@
       <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
- The <xref:System.Double> value type represents a double-precision 64-bit number with values ranging from negative 1.79769313486232e308 to positive 1.79769313486232e308, as well as positive or negative zero, <xref:System.Double.PositiveInfinity>, <xref:System.Double.NegativeInfinity>, and not a number (<xref:System.Double.NaN>). It is intended to represent values that are extremely large (such as distances between planets or galaxies) or extremely small (the molecular mass of a substance in kilograms) and that often are imprecise (such as the distance from earth to another solar system), The <xref:System.Double> type complies with the IEC 60559:1989 (IEEE 754) standard for binary floating-point arithmetic.  
+ The <xref:System.Double> value type represents a double-precision 64-bit number with values ranging from negative 1.79769313486232e308 to positive 1.79769313486232e308, as well as positive or negative zero, <xref:System.Double.PositiveInfinity>, <xref:System.Double.NegativeInfinity>, and not a number (<xref:System.Double.NaN>). It is intended to represent values that are extremely large (such as distances between planets or galaxies) or extremely small (such as the molecular mass of a substance in kilograms) and that often are imprecise (such as the distance from earth to another solar system). The <xref:System.Double> type complies with the IEC 60559:1989 (IEEE 754) standard for binary floating-point arithmetic.  
   
  This topic consists of the following sections:  
   
@@ -1815,6 +1815,7 @@
       <Docs>
         <summary>Converts the string representation of a number to its double-precision floating-point number equivalent.</summary>
         <altmember cref="Overload:System.Double.TryParse" />
+        <remarks>In .NET Core 3.0 and later, values that are too large to represent are rounded to <see cref="F:System.Double.PositiveInfinity"/> or <see cref="F:System.Double.NegativeInfinity"/> as required by the IEEE 754 specification. In prior versions, including .NET Framework, parsing a value that was too large to represent resulted in failure.</remarks>
       </Docs>
     </MemberGroup>
     <Member MemberName="Parse">
@@ -1861,6 +1862,8 @@
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
+ In .NET Core 3.0 and later, values that are too large to represent are rounded to <xref:System.Double.PositiveInfinity> or <xref:System.Double.NegativeInfinity> as required by the IEEE 754 specification. In prior versions, including .NET Framework, parsing a value that was too large to represent resulted in failure.
+
  The `s` parameter can contain the current culture's <xref:System.Globalization.NumberFormatInfo.PositiveInfinitySymbol%2A?displayProperty=nameWithType>, <xref:System.Globalization.NumberFormatInfo.NegativeInfinitySymbol%2A?displayProperty=nameWithType>, <xref:System.Globalization.NumberFormatInfo.NaNSymbol%2A?displayProperty=nameWithType>, or a string of the form:  
   
  [*ws*][*sign*][*integral-digits*[*,*]]*integral-digits*[*.*[*fractional-digits*]][E[*sign*]*exponential-digits*][*ws*]  
@@ -1959,6 +1962,8 @@ If a separator is encountered in the `s` parameter during a parse operation, and
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
+ In .NET Core 3.0 and later, values that are too large to represent are rounded to <xref:System.Double.PositiveInfinity> or <xref:System.Double.NegativeInfinity> as required by the IEEE 754 specification. In prior versions, including .NET Framework, parsing a value that was too large to represent resulted in failure.
+
  The `style` parameter defines the style elements (such as white space, thousands separators, and currency symbols) that are allowed in the `s` parameter for the parse operation to succeed. It must be a combination of bit flags from the <xref:System.Globalization.NumberStyles> enumeration. The following <xref:System.Globalization.NumberStyles> members are not supported:  
   
 -   <xref:System.Globalization.NumberStyles.AllowHexSpecifier>  
@@ -2089,6 +2094,8 @@ If a separator is encountered in the `s` parameter during a parse operation, and
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
+ In .NET Core 3.0 and later, values that are too large to represent are rounded to <xref:System.Double.PositiveInfinity> or <xref:System.Double.NegativeInfinity> as required by the IEEE 754 specification. In prior versions, including .NET Framework, parsing a value that was too large to represent resulted in failure.
+
  This overload of the <xref:System.Double.Parse%28System.String%2CSystem.IFormatProvider%29> method is typically used to convert text that can be formatted in a variety of ways to a <xref:System.Double> value. For example, it can be used to convert the text that is entered by a user into an HTML text box to a numeric value.  
   
  The `s` parameter is interpreted using a combination of the <xref:System.Globalization.NumberStyles.Float?displayProperty=nameWithType> and <xref:System.Globalization.NumberStyles.AllowThousands?displayProperty=nameWithType> flags. The `s` parameter can contain <xref:System.Globalization.NumberFormatInfo.PositiveInfinitySymbol%2A?displayProperty=nameWithType>, <xref:System.Globalization.NumberFormatInfo.NegativeInfinitySymbol%2A?displayProperty=nameWithType>, or <xref:System.Globalization.NumberFormatInfo.NaNSymbol%2A?displayProperty=nameWithType> for the culture specified by `provider`, or it can contain a string of the form:  
@@ -2177,6 +2184,8 @@ If a separator is encountered in the `s` parameter during a parse operation, and
         <remarks>
           <format type="text/markdown"><![CDATA[  
 
+In .NET Core 3.0 and later, values that are too large to represent are rounded to <xref:System.Double.PositiveInfinity> or <xref:System.Double.NegativeInfinity> as required by the IEEE 754 specification. In prior versions, including .NET Framework, parsing a value that was too large to represent resulted in failure.
+
 If `s` is out of range of the <xref:System.Double> data type, the method returns <xref:System.Double.NegativeInfinity?displayProperty=nameWithType> if `s` is less than <xref:System.Double.MinValue?displayProperty=nameWithType> and <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> if `s` is greater than <xref:System.Double.MaxValue?displayProperty=nameWithType>.
 
          ]]></format>
@@ -2239,6 +2248,8 @@ If `s` is out of range of the <xref:System.Double> data type, the method returns
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
+ In .NET Core 3.0 and later, values that are too large to represent are rounded to <xref:System.Double.PositiveInfinity> or <xref:System.Double.NegativeInfinity> as required by the IEEE 754 specification. In prior versions, including .NET Framework, parsing a value that was too large to represent resulted in failure.
+
  The `style` parameter defines the style elements (such as white space, thousands separators, and currency symbols) that are allowed in the `s` parameter for the parse operation to succeed. It must be a combination of bit flags from the <xref:System.Globalization.NumberStyles> enumeration. The following <xref:System.Globalization.NumberStyles> members are not supported:  
   
 -   <xref:System.Globalization.NumberStyles.AllowHexSpecifier>  
@@ -3690,6 +3701,7 @@ If a separator is encountered in the `s` parameter during a parse operation, and
       </AssemblyInfo>
       <Docs>
         <summary>Converts the string representation of a number to its double-precision floating-point number equivalent. A return value indicates whether the conversion succeeded or failed.</summary>
+        <remarks>In .NET Core 3.0 and later, values that are too large to represent are rounded to <see cref="F:System.Double.PositiveInfinity"/> or <see cref="F:System.Double.NegativeInfinity"/> as required by the IEEE 754 specification. In prior versions, including .NET Framework, parsing a value that was too large to represent resulted in failure.</remarks>
         <altmember cref="Overload:System.Double.Parse" />
       </Docs>
     </MemberGroup>
@@ -3726,7 +3738,7 @@ If a separator is encountered in the `s` parameter during a parse operation, and
         <summary>Converts the span representation of a number in a specified style and culture-specific format to its double-precision floating-point number equivalent. A return value indicates whether the conversion succeeded or failed.</summary>
         <returns>
           <see langword="true" /> if <paramref name="s" /> was converted successfully; otherwise, <see langword="false" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>In .NET Core 3.0 and later, values that are too large to represent are rounded to <see cref="F:System.Double.PositiveInfinity"/> or <see cref="F:System.Double.NegativeInfinity"/> as required by the IEEE 754 specification. In prior versions, including .NET Framework, parsing a value that was too large to represent resulted in failure.</remarks>
       </Docs>
     </Member>
     <Member MemberName="TryParse">
@@ -3780,6 +3792,8 @@ If a separator is encountered in the `s` parameter during a parse operation, and
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
+ In .NET Core 3.0 and later, values that are too large to represent are rounded to <xref:System.Double.PositiveInfinity> or <xref:System.Double.NegativeInfinity> as required by the IEEE 754 specification. In prior versions, including .NET Framework, parsing a value that was too large to represent resulted in failure.
+
  This overload differs from the <xref:System.Double.Parse%28System.String%29?displayProperty=nameWithType> method by returning a Boolean value that indicates whether the parse operation succeeded instead of returning the parsed numeric value. It eliminates the need to use exception handling to test for a <xref:System.FormatException> in the event that `s` is invalid and cannot be successfully parsed.  
   
  The `s` parameter can contain the current culture's <xref:System.Globalization.NumberFormatInfo.PositiveInfinitySymbol%2A?displayProperty=nameWithType>, <xref:System.Globalization.NumberFormatInfo.NegativeInfinitySymbol%2A?displayProperty=nameWithType>, <xref:System.Globalization.NumberFormatInfo.NaNSymbol%2A?displayProperty=nameWithType> (the string comparison is case-sensitive), or a string of the form:  
@@ -3868,7 +3882,7 @@ If a separator is encountered in the `s` parameter during a parse operation, and
         <summary>Converts a character span containing the string representation of a number in a specified style and culture-specific format to its double-precision floating-point number equivalent. A return value indicates whether the conversion succeeded or failed.</summary>
         <returns>
           <see langword="true" /> if <paramref name="s" /> was converted successfully; otherwise, <see langword="false" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>In .NET Core 3.0 and later, values that are too large to represent are rounded to <see cref="F:System.Double.PositiveInfinity"/> or <see cref="F:System.Double.NegativeInfinity"/> as required by the IEEE 754 specification. In prior versions, including .NET Framework, parsing a value that was too large to represent resulted in failure.</remarks>
       </Docs>
     </Member>
     <Member MemberName="TryParse">
@@ -3927,6 +3941,8 @@ If a separator is encountered in the `s` parameter during a parse operation, and
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
+ In .NET Core 3.0 and later, values that are too large to represent are rounded to <xref:System.Double.PositiveInfinity> or <xref:System.Double.NegativeInfinity> as required by the IEEE 754 specification. In prior versions, including .NET Framework, parsing a value that was too large to represent resulted in failure.
+
  The <xref:System.Double.TryParse%2A> method is like the <xref:System.Double.Parse%28System.String%2CSystem.Globalization.NumberStyles%2CSystem.IFormatProvider%29> method, except this method does not throw an exception if the conversion fails. If the conversion succeeds, the return value is `true` and the `result` parameter is set to the outcome of the conversion. If the conversion fails, the return value is `false` and the `result` parameter is set to zero. This eliminates the need to use exception handling to test for a <xref:System.FormatException> in the event that `s` is invalid and cannot be successfully parsed.  
   
  The `style` parameter defines the allowable format of the `s` parameter for the parse operation to succeed. It must be a combination of bit flags from the <xref:System.Globalization.NumberStyles> enumeration. The following <xref:System.Globalization.NumberStyles> members are not supported: