Clarify MidpointRounding docs: round-to-nearest vs directed rounding (#12875)

Author: Copilot

xml/System/MidpointRounding.xml

@@ -55,7 +55,10 @@
 
 Use the <xref:System.MidpointRounding> enumeration with appropriate overloads of <xref:System.Math.Round*?displayProperty=nameWithType>, <xref:System.MathF.Round*?displayProperty=nameWithType>, and <xref:System.Decimal.Round*?displayProperty=nameWithType> to provide more control of the rounding process.
 
-There are two overall rounding strategies&mdash;*round to nearest* and *directed rounding*&mdash;and each enumeration field participates in exactly one of these strategies.
+Despite the enumeration's name, not every mode is only about how midpoints are handled. <xref:System.MidpointRounding> defines two overall rounding strategies&mdash;*round to nearest* and *directed rounding*&mdash;and each enumeration field participates in exactly one of these strategies:
+
+- The *round-to-nearest* modes (<xref:System.MidpointRounding.AwayFromZero> and <xref:System.MidpointRounding.ToEven>) always round to the nearest representable value. They only differ from each other when the input is exactly halfway between two values (a *midpoint*), which is what the enumeration's name refers to.
+- The *directed rounding* modes (<xref:System.MidpointRounding.ToNegativeInfinity>, <xref:System.MidpointRounding.ToPositiveInfinity>, and <xref:System.MidpointRounding.ToZero>) always round every value&mdash;not just midpoints&mdash;in a fixed direction. The result is the nearest representable value in that direction, even when the input isn't a midpoint.
 
 ## Round to nearest
 
@@ -66,9 +69,9 @@ Fields:
 
 A round-to-nearest operation takes an original number with an implicit or specified precision; examines the next digit, which is at that precision plus one; and returns the nearest number with the same precision as the original number. For positive numbers, if the next digit is from 0 through 4, the nearest number is toward negative infinity. If the next digit is from 6 through 9, the nearest number is toward positive infinity. For negative numbers, if the next digit is from 0 through 4, the nearest number is toward positive infinity. If the next digit is from 6 through 9, the nearest number is toward negative infinity.
 
-If the next digit is from 0 through 4 or 6 through 9, the `MidpointRounding.AwayFromZero` and `MidpointRounding.ToEven` do not affect the result of the rounding operation. However, if the next digit is 5, which is the midpoint between two possible results, and all remaining digits are zero or there are no remaining digits, the nearest number is ambiguous. In this case, the round-to-nearest modes in `MidpointRounding` enable you to specify whether the rounding operation returns the nearest number away from zero or the nearest even number.
+If the next digit is from 0 through 4 or 6 through 9, the choice between <xref:System.MidpointRounding.AwayFromZero> and <xref:System.MidpointRounding.ToEven> doesn't affect the result of the rounding operation. However, if the next digit is 5, which is the midpoint between two possible results, and all remaining digits are zero or there are no remaining digits, the nearest number is ambiguous. In this case, the round-to-nearest modes in <xref:System.MidpointRounding> enable you to specify whether the rounding operation returns the nearest number away from zero or the nearest even number.
 
-The following table demonstrates the results of rounding some negative and positive numbers in conjunction with round-to-nearest modes. The precision used to round the numbers is zero, which means the number after the decimal point affects the rounding operation. For example, for the number -2.5, the digit after the decimal point is 5. Because that digit is the midpoint, you can use a `MidpointRounding` value to determine the result of rounding. If `AwayFromZero` is specified, -3 is returned because it is the nearest number away from zero with a precision of zero. If `ToEven` is specified, -2 is returned because it is the nearest even number with a precision of zero.
+The following table demonstrates the results of rounding some negative and positive numbers in conjunction with round-to-nearest modes. The precision used to round the numbers is zero, which means the number after the decimal point affects the rounding operation. For example, for the number -2.5, the digit after the decimal point is 5. Because that digit is the midpoint, you can use a <xref:System.MidpointRounding> value to determine the result of rounding. If <xref:System.MidpointRounding.AwayFromZero> is specified, -3 is returned because it is the nearest number away from zero with a precision of zero. If <xref:System.MidpointRounding.ToEven> is specified, -2 is returned because it is the nearest even number with a precision of zero.
 
 | Original number | AwayFromZero | ToEven |
 |-----------------|--------------|--------|
@@ -89,7 +92,7 @@ Fields:
 - <xref:System.MidpointRounding.ToPositiveInfinity>
 - <xref:System.MidpointRounding.ToZero>
 
-A directed-rounding operation takes an original number with an implicit or specified precision and returns the next closest number in a specific direction with the same precision as the original number. Directed modes on `MidpointRounding` control toward which predefined number the rounding is performed.
+A directed-rounding operation takes an original number with an implicit or specified precision and returns the next closest number in a specific direction with the same precision as the original number. Directed modes on <xref:System.MidpointRounding> control the direction toward which every value is rounded. Unlike the round-to-nearest modes, these modes apply to every input value, not just midpoints; for example, <xref:System.MidpointRounding.ToPositiveInfinity> rounds 2.1, 2.5, and 2.8 all up to 3.
 
 The following table demonstrates the results of rounding some negative and positive numbers in conjunction with directed-rounding modes. The precision used to round the numbers is zero, which means the number before the decimal point is affected by the rounding operation.
 
@@ -153,7 +156,7 @@ The following table demonstrates the results of rounding some negative and posit
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>The strategy of rounding to the nearest number, and when a number is halfway between two others, it's rounded toward the nearest number that's away from zero.</summary>
+        <summary>The strategy of rounding to the nearest number. When a number is halfway between two others, it's rounded toward the nearest number that's away from zero. Non-midpoint values are unaffected by this choice and are rounded to the nearest representable value.</summary>
       </Docs>
     </Member>
     <Member MemberName="ToEven">
@@ -193,7 +196,7 @@ The following table demonstrates the results of rounding some negative and posit
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>The strategy of rounding to the nearest number, and when a number is halfway between two others, it's rounded toward the nearest even number.</summary>
+        <summary>The strategy of rounding to the nearest number. When a number is halfway between two others, it's rounded toward the nearest even number. Non-midpoint values are unaffected by this choice and are rounded to the nearest representable value. Also known as banker's rounding.</summary>
       </Docs>
     </Member>
     <Member MemberName="ToNegativeInfinity">
@@ -222,7 +225,7 @@ The following table demonstrates the results of rounding some negative and posit
       </ReturnValue>
       <MemberValue>3</MemberValue>
       <Docs>
-        <summary>The strategy of downwards-directed rounding, with the result closest to and no greater than the infinitely precise result.</summary>
+        <summary>The strategy of downwards-directed rounding, where every value—not just midpoints—is rounded toward negative infinity. The result is the value closest to and no greater than the infinitely precise result. When rounding to zero digits, this is equivalent to the mathematical floor function; when rounding to a non-zero number of digits, it applies the same behavior at the specified precision.</summary>
       </Docs>
     </Member>
     <Member MemberName="ToPositiveInfinity">
@@ -251,7 +254,7 @@ The following table demonstrates the results of rounding some negative and posit
       </ReturnValue>
       <MemberValue>4</MemberValue>
       <Docs>
-        <summary>The strategy of upwards-directed rounding, with the result closest to and no less than the infinitely precise result.</summary>
+        <summary>The strategy of upwards-directed rounding, where every value—not just midpoints—is rounded toward positive infinity. The result is the value closest to and no less than the infinitely precise result. When rounding to zero digits, this is equivalent to the mathematical ceiling function; when rounding to a non-zero number of digits, it applies the same behavior at the specified precision.</summary>
       </Docs>
     </Member>
     <Member MemberName="ToZero">
@@ -280,7 +283,7 @@ The following table demonstrates the results of rounding some negative and posit
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>The strategy of directed rounding toward zero, with the result closest to and no greater in magnitude than the infinitely precise result.</summary>
+        <summary>The strategy of directed rounding toward zero, where every value—not just midpoints—is rounded toward zero. The result is the value closest to and no greater in magnitude than the infinitely precise result. When rounding to zero digits, this is equivalent to truncation; when rounding to a non-zero number of digits, it truncates toward zero at the specified precision.</summary>
       </Docs>
     </Member>
   </Members>