From c33d2627d7db19bee74b35c7b64000ed06cba8d4 Mon Sep 17 00:00:00 2001
From: carlossanlop <calope@microsoft.com>
Date: Thu, 1 Aug 2019 15:03:18 -0700
Subject: [PATCH 01/10] Document System.Numerics APIs: op_Addition,
 op_Division, op_Multiply, op_Substraction, Substract

---
 xml/System.Numerics/Complex.xml | 376 +++++++++++++++++++-------------
 1 file changed, 224 insertions(+), 152 deletions(-)

diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml
index dabce831640..90bd6ef99b5 100644
--- a/xml/System.Numerics/Complex.xml
+++ b/xml/System.Numerics/Complex.xml
@@ -1832,6 +1832,45 @@
         <altmember cref="F:System.Numerics.Complex.Zero" />
       </Docs>
     </Member>
+    <MemberGroup MemberName="op_Addition">
+      <AssemblyInfo>
+        <AssemblyName>System.Runtime.Numerics</AssemblyName>
+        <AssemblyVersion>4.1.1.0</AssemblyVersion>
+      </AssemblyInfo>
+      <Docs>
+        <summary>Adds a specified number to another specified number.</summary>
+        <remarks>
+          <format type="text/markdown">
+            <![CDATA[
+
+## Remarks
+
+The <xref:System.Numerics.Complex.op_Addition%2A> method defines the addition operation for complex numbers. It enables code such as the following:
+
+[!code-csharp[System.Numerics.Complex.Add#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.add/cs/add3.cs#3)]
+[!code-vb[System.Numerics.Complex.Add#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.add/vb/add3.vb#3)]
+
+The addition of a complex number, a + bi, and a second complex number, c + di, takes the following form:
+
+(a + c) + (b + d)i
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%2A> method instead.
+
+The equivalent method for this operator is <xref:System.Numerics.Complex.Add%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>.
+
+## Examples
+
+The following example illustrates addition with complex numbers.
+
+[!code-csharp[System.Numerics.Complex.Add#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.add/cs/add2.cs#2)]
+[!code-vb[System.Numerics.Complex.Add#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.add/vb/add2.vb#2)]
+
+          ]]></format>
+        </remarks>
+      </Docs>
+    </MemberGroup>
     <Member MemberName="op_Addition">
       <MemberSignature Language="C#" Value="public static System.Numerics.Complex operator + (double left, System.Numerics.Complex right);" />
       <MemberSignature Language="ILAsm" Value=".method public static hidebysig specialname valuetype System.Numerics.Complex op_Addition(float64 left, valuetype System.Numerics.Complex right) cil managed" />
@@ -1858,11 +1897,12 @@
         <Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">To be added.</param>
-        <param name="right">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="left">The double value to add.</param>
+        <param name="right">The complex value to add.</param>
+        <summary>Adds a double number to a complex number.</summary>
+        <returns>The sum of <paramref name="left" /> and <paramref name="right" /> as a complex number.</returns>
         <remarks>To be added.</remarks>
+        <altmember cref="M:System.Numerics.Complex.Add(System.NDouble,System.Numerics.Complex)" />
       </Docs>
     </Member>
     <Member MemberName="op_Addition">
@@ -1891,11 +1931,12 @@
         <Parameter Name="right" Type="System.Double" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">To be added.</param>
-        <param name="right">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="left">The complex value to add.</param>
+        <param name="right">The double value to add.</param>
+        <summary>Adds a complex number to a double number.</summary>
+        <returns>The sum of <paramref name="left" /> and <paramref name="right" /> as a complex number.</returns>
         <remarks>To be added.</remarks>
+        <altmember cref="M:System.Numerics.Complex.Add(System.Numerics.Complex,System.Double)" />
       </Docs>
     </Member>
     <Member MemberName="op_Addition">
@@ -1930,40 +1971,45 @@
         <Parameter Name="right" Type="System.Numerics.Complex" />
       </Parameters>
       <Docs>
-        <param name="left">The first value to add.</param>
-        <param name="right">The second value to add.</param>
+        <param name="left">The first complex value to add.</param>
+        <param name="right">The second complex value to add.</param>
         <summary>Adds two complex numbers.</summary>
         <returns>The sum of <paramref name="left" /> and <paramref name="right" />.</returns>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The <xref:System.Numerics.Complex.op_Addition%2A> method defines the addition operation for complex numbers. It enables code such as the following:  
-  
- [!code-csharp[System.Numerics.Complex.Add#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.add/cs/add3.cs#3)]
- [!code-vb[System.Numerics.Complex.Add#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.add/vb/add3.vb#3)]  
-  
- The addition of a complex number, a + bi, and a second complex number, c + di, takes the following form:  
-  
- (a + c) + (b + d)i  
-  
- If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.  
-  
- Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%2A> method instead.  
-  
- The equivalent method for this operator is <xref:System.Numerics.Complex.Add%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>  
-  
-## Examples  
- The following example illustrates addition with complex numbers.  
-  
- [!code-csharp[System.Numerics.Complex.Add#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.add/cs/add2.cs#2)]
- [!code-vb[System.Numerics.Complex.Add#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.add/vb/add2.vb#2)]  
-  
- ]]></format>
-        </remarks>
+        <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Add(System.Numerics.Complex,System.Numerics.Complex)" />
       </Docs>
     </Member>
+    <MemberGroup MemberName="op_Division">
+      <AssemblyInfo>
+        <AssemblyName>System.Runtime.Numerics</AssemblyName>
+        <AssemblyVersion>4.1.1.0</AssemblyVersion>
+      </AssemblyInfo>
+      <Docs>
+        <summary>Divides a specified number by another specified number.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The <xref:System.Numerics.Complex.op_Division%2A> method defines the division operation for complex numbers. It enables code such as the following:
+
+[!code-csharp[System.Numerics.Complex.Divide#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.divide/cs/divide2.cs#2)]
+[!code-vb[System.Numerics.Complex.Divide#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.divide/vb/divide2.vb#2)]
+
+The division of a complex number, a + bi, and a second complex number, c + di, takes the following form:
+
+((ac + bd) / (c<sup>2</sup> + d<sup>2</sup>)) + ((bc - ad) / (c<sup>2</sup> + d<sup>2</sup>)i
+
+If the division results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%2A> method instead.
+
+The equivalent method for this operator is <xref:System.Numerics.Complex.Divide%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>.
+
+          ]]></format>
+        </remarks>
+      </Docs>
+    </MemberGroup>
     <Member MemberName="op_Division">
       <MemberSignature Language="C#" Value="public static System.Numerics.Complex operator / (double left, System.Numerics.Complex right);" />
       <MemberSignature Language="ILAsm" Value=".method public static hidebysig specialname valuetype System.Numerics.Complex op_Division(float64 left, valuetype System.Numerics.Complex right) cil managed" />
@@ -1990,11 +2036,12 @@
         <Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">To be added.</param>
-        <param name="right">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="left">The double value to be divided.</param>
+        <param name="right">The complex value to divide by.</param>
+        <summary>Divides a specified double number by a specified complex number.</summary>
+        <returns>The result of dividing <paramref name="left" /> by <paramref name="right" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
+        <altmember cref="M:System.Numerics.Complex.Divide(System.Double,System.Numerics.Complex)" />
       </Docs>
     </Member>
     <Member MemberName="op_Division">
@@ -2023,11 +2070,12 @@
         <Parameter Name="right" Type="System.Double" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">To be added.</param>
-        <param name="right">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="left">The complex value to be divided.</param>
+        <param name="right">The double value to divide by.</param>
+        <summary>Divides a specified complex number by a specified double number.</summary>
+        <returns>The result of dividing <paramref name="left" /> by <paramref name="right" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
+        <altmember cref="M:System.Numerics.Complex.Divide(System.Numerics.Complex,System.Double)" />
       </Docs>
     </Member>
     <Member MemberName="op_Division">
@@ -2062,29 +2110,11 @@
         <Parameter Name="right" Type="System.Numerics.Complex" />
       </Parameters>
       <Docs>
-        <param name="left">The value to be divided.</param>
-        <param name="right">The value to divide by.</param>
+        <param name="left">The complex value to be divided.</param>
+        <param name="right">The complex value to divide by.</param>
         <summary>Divides a specified complex number by another specified complex number.</summary>
         <returns>The result of dividing <paramref name="left" /> by <paramref name="right" />.</returns>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The <xref:System.Numerics.Complex.op_Division%2A> method defines the division operation for complex numbers. It enables code such as the following:  
-  
- [!code-csharp[System.Numerics.Complex.Divide#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.divide/cs/divide2.cs#2)]
- [!code-vb[System.Numerics.Complex.Divide#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.divide/vb/divide2.vb#2)]  
-  
- The division of a complex number, a + bi, and a second complex number, c + di, takes the following form:  
-  
- ((ac + bd) / (c<sup>2</sup> + d<sup>2</sup>)) + ((bc - ad) / (c<sup>2</sup> + d<sup>2</sup>)i  
-  
- If the division results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.  
-  
- Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%2A> method instead.  
-  
- The equivalent method for this operator is <xref:System.Numerics.Complex.Divide%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>]]></format>
-        </remarks>
+        <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Divide(System.Numerics.Complex,System.Numerics.Complex)" />
       </Docs>
     </Member>
@@ -2851,6 +2881,37 @@ This API is not CLS-compliant.</summary>
         <altmember cref="M:System.Numerics.Complex.op_Equality(System.Numerics.Complex,System.Numerics.Complex)" />
       </Docs>
     </Member>
+    <MemberGroup MemberName="op_Multiply">
+      <AssemblyInfo>
+        <AssemblyName>System.Runtime.Numerics</AssemblyName>
+        <AssemblyVersion>4.1.1.0</AssemblyVersion>
+      </AssemblyInfo>
+      <Docs>
+        <summary>Multiplies a specified number by another specified number.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The <xref:System.Numerics.Complex.op_Multiply%2A> method defines the operation of the multiplication operator for complex numbers. It enables code such as the following:
+
+[!code-csharp[System.Numerics.Complex.Multiply#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.multiply/cs/multiply2.cs#2)]
+[!code-vb[System.Numerics.Complex.Multiply#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.multiply/vb/multiply2.vb#2)]
+
+The multiplication of a complex number, a + bi, and a second complex number, c + di, takes the following form:
+
+(ac - bd) + (ad + bc)i
+
+If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%2A> method instead.
+
+The equivalent method for this operator is <xref:System.Numerics.Complex.Multiply%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>]]>.
+
+          </format>
+        </remarks>
+      </Docs>
+    </MemberGroup>
     <Member MemberName="op_Multiply">
       <MemberSignature Language="C#" Value="public static System.Numerics.Complex operator * (double left, System.Numerics.Complex right);" />
       <MemberSignature Language="ILAsm" Value=".method public static hidebysig specialname valuetype System.Numerics.Complex op_Multiply(float64 left, valuetype System.Numerics.Complex right) cil managed" />
@@ -2877,11 +2938,12 @@ This API is not CLS-compliant.</summary>
         <Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">To be added.</param>
-        <param name="right">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="left">The double value to multiply.</param>
+        <param name="right">The complex value to multiply.</param>
+        <summary>Multiplies a specified double number by a specified complex number.</summary>
+        <returns>The product of <paramref name="left" /> and <paramref name="right" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
+        <altmember cref="M:System.Numerics.Complex.Multiply(System.Double,System.Numerics.Complex)" />
       </Docs>
     </Member>
     <Member MemberName="op_Multiply">
@@ -2910,11 +2972,12 @@ This API is not CLS-compliant.</summary>
         <Parameter Name="right" Type="System.Double" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">To be added.</param>
-        <param name="right">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="left">The complex value to multiply.</param>
+        <param name="right">The double value to multiply.</param>
+        <summary>Multiplies specified complex number by a specified double number.</summary>
+        <returns>The product of <paramref name="left" /> and <paramref name="right" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
+        <altmember cref="M:System.Numerics.Complex.Multiply(System.Numerics.Complex,System.Double)" />
       </Docs>
     </Member>
     <Member MemberName="op_Multiply">
@@ -2949,32 +3012,45 @@ This API is not CLS-compliant.</summary>
         <Parameter Name="right" Type="System.Numerics.Complex" />
       </Parameters>
       <Docs>
-        <param name="left">The first value to multiply.</param>
-        <param name="right">The second value to multiply.</param>
+        <param name="left">The first complex value to multiply.</param>
+        <param name="right">The second complex value to multiply.</param>
         <summary>Multiplies two specified complex numbers.</summary>
         <returns>The product of <paramref name="left" /> and <paramref name="right" />.</returns>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The <xref:System.Numerics.Complex.op_Multiply%2A> method defines the operation of the multiplication operator for complex numbers. It enables code such as the following:  
-  
- [!code-csharp[System.Numerics.Complex.Multiply#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.multiply/cs/multiply2.cs#2)]
- [!code-vb[System.Numerics.Complex.Multiply#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.multiply/vb/multiply2.vb#2)]  
-  
- The multiplication of a complex number, a + bi, and a second complex number, c + di, takes the following form:  
-  
- (ac - bd) + (ad + bc)i  
-  
- If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.  
-  
- Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%2A> method instead.  
-  
- The equivalent method for this operator is <xref:System.Numerics.Complex.Multiply%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>]]></format>
-        </remarks>
+        <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Multiply(System.Numerics.Complex,System.Numerics.Complex)" />
       </Docs>
     </Member>
+    <MemberGroup MemberName="op_Subtraction">
+      <AssemblyInfo>
+        <AssemblyName>System.Runtime.Numerics</AssemblyName>
+        <AssemblyVersion>4.1.1.0</AssemblyVersion>
+      </AssemblyInfo>
+      <Docs>
+        <summary>Substracts a specified number from another specified number.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The <xref:System.Numerics.Complex.op_Subtraction%2A> method defines the operation of the subtraction operator for complex numbers. It enables code such as the following:
+
+[!code-csharp[System.Numerics.Complex.Subtract#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.subtract/cs/subtract2.cs#2)]
+[!code-vb[System.Numerics.Complex.Subtract#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.subtract/vb/subtract2.vb#2)]
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form:
+
+(a - c) + (b - d)i
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%2A> method instead.
+
+The equivalent method for this operator is <xref:System.Numerics.Complex.Subtract%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>.
+ 
+          ]]></format>
+        </remarks>
+      </Docs>
+    </MemberGroup>
     <Member MemberName="op_Subtraction">
       <MemberSignature Language="C#" Value="public static System.Numerics.Complex operator - (double left, System.Numerics.Complex right);" />
       <MemberSignature Language="ILAsm" Value=".method public static hidebysig specialname valuetype System.Numerics.Complex op_Subtraction(float64 left, valuetype System.Numerics.Complex right) cil managed" />
@@ -3001,11 +3077,12 @@ This API is not CLS-compliant.</summary>
         <Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">To be added.</param>
-        <param name="right">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="left">The double value to subtract from (the minuend).</param>
+        <param name="right">The complex value to subtract (the subtrahend).</param>
+        <summary>Subtracts a complex number from a double number.</summary>
+        <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
+        <altmember cref="M:System.Numerics.Complex.Subtract(System.Double,System.Numerics.Complex)" />
       </Docs>
     </Member>
     <Member MemberName="op_Subtraction">
@@ -3034,11 +3111,12 @@ This API is not CLS-compliant.</summary>
         <Parameter Name="right" Type="System.Double" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">To be added.</param>
-        <param name="right">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="left">The complex value to subtract from (the minuend).</param>
+        <param name="right">The double value to subtract (the subtrahend).</param>
+        <summary>Subtracts a double number from a complex number.</summary>
+        <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
+        <altmember cref="M:System.Numerics.Complex.Subtract(System.Numerics.Complex,System.Double)" />
       </Docs>
     </Member>
     <Member MemberName="op_Subtraction">
@@ -3077,25 +3155,7 @@ This API is not CLS-compliant.</summary>
         <param name="right">The value to subtract (the subtrahend).</param>
         <summary>Subtracts a complex number from another complex number.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />.</returns>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The <xref:System.Numerics.Complex.op_Subtraction%2A> method defines the operation of the subtraction operator for complex numbers. It enables code such as the following:  
-  
- [!code-csharp[System.Numerics.Complex.Subtract#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.subtract/cs/subtract2.cs#2)]
- [!code-vb[System.Numerics.Complex.Subtract#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.subtract/vb/subtract2.vb#2)]  
-  
- If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.  
-  
- The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form:  
-  
- (a - c) + (b - d)i  
-  
- Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%2A> method instead.  
-  
- The equivalent method for this operator is <xref:System.Numerics.Complex.Subtract%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>]]></format>
-        </remarks>
+        <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Subtract(System.Numerics.Complex,System.Numerics.Complex)" />
       </Docs>
     </Member>
@@ -3572,6 +3632,37 @@ This API is not CLS-compliant.</summary>
         </remarks>
       </Docs>
     </Member>
+    <MemberGroup MemberName="Subtract">
+      <AssemblyInfo>
+        <AssemblyName>System.Runtime.Numerics</AssemblyName>
+        <AssemblyVersion>4.1.1.0</AssemblyVersion>
+      </AssemblyInfo>
+      <Docs>
+        <summary>Substracts a specified number from another specified number and returns the result.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form:
+
+(a - c) + (b - d)i
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can use the <xref:System.Numerics.Complex.Subtract%2A> method to perform subtraction using complex numbers.
+
+## Examples
+
+The following example subtracts each complex number in an array from a complex number.
+
+[!code-csharp[System.Numerics.Complex.Subtract#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.subtract/cs/subtract1.cs#1)]
+[!code-vb[System.Numerics.Complex.Subtract#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.subtract/vb/subtract1.vb#1)]
+
+          ]]></format>
+        </remarks>
+      </Docs>
+    </MemberGroup>
     <Member MemberName="Subtract">
       <MemberSignature Language="C#" Value="public static System.Numerics.Complex Subtract (double left, System.Numerics.Complex right);" />
       <MemberSignature Language="ILAsm" Value=".method public static hidebysig valuetype System.Numerics.Complex Subtract(float64 left, valuetype System.Numerics.Complex right) cil managed" />
@@ -3598,11 +3689,12 @@ This API is not CLS-compliant.</summary>
         <Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">To be added.</param>
-        <param name="right">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="left">The double value to subtract from (the minuend).</param>
+        <param name="right">The complex value to subtract (the subtrahend).</param>
+        <summary>Subtracts one complex number from a double number and returns the result.</summary>
+        <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
+        <altmember cref="M:System.Numerics.Complex.op_Subtraction(System.Double,System.Numerics.Complex)" />
       </Docs>
     </Member>
     <Member MemberName="Subtract">
@@ -3631,11 +3723,12 @@ This API is not CLS-compliant.</summary>
         <Parameter Name="right" Type="System.Double" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">To be added.</param>
-        <param name="right">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="left">The complex value to subtract from (the minuend).</param>
+        <param name="right">The double value to subtract (the subtrahend).</param>
+        <summary>Subtracts one double number from a complex number and returns the result.</summary>
+        <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
+        <altmember cref="M:System.Numerics.Complex.op_Subtraction(System.Numerics.Complex,System.Double)" />
       </Docs>
     </Member>
     <Member MemberName="Subtract">
@@ -3679,28 +3772,7 @@ This API is not CLS-compliant.</summary>
         <param name="right">The value to subtract (the subtrahend).</param>
         <summary>Subtracts one complex number from another and returns the result.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />.</returns>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form:  
-  
- (a - c) + (b - d)i  
-  
- If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.  
-  
- Languages that do not support custom operators can use the <xref:System.Numerics.Complex.Subtract%2A> method to perform subtraction using complex numbers.  
-  
-   
-  
-## Examples  
- The following example subtracts each complex number in an array from a complex number.  
-  
- [!code-csharp[System.Numerics.Complex.Subtract#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.subtract/cs/subtract1.cs#1)]
- [!code-vb[System.Numerics.Complex.Subtract#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.subtract/vb/subtract1.vb#1)]  
-  
- ]]></format>
-        </remarks>
+        <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.op_Subtraction(System.Numerics.Complex,System.Numerics.Complex)" />
       </Docs>
     </Member>

From ceab30e96ec3c5ebda138040b5dc6302f11d6638 Mon Sep 17 00:00:00 2001
From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com>
Date: Fri, 2 Aug 2019 10:10:40 -0700
Subject: [PATCH 02/10] suggestions by Jozkee and tannergooding

---
 xml/System.Numerics/Complex.xml | 52 ++++++++++++++++-----------------
 1 file changed, 26 insertions(+), 26 deletions(-)

diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml
index 90bd6ef99b5..82652d17b80 100644
--- a/xml/System.Numerics/Complex.xml
+++ b/xml/System.Numerics/Complex.xml
@@ -1838,7 +1838,7 @@
         <AssemblyVersion>4.1.1.0</AssemblyVersion>
       </AssemblyInfo>
       <Docs>
-        <summary>Adds a specified number to another specified number.</summary>
+        <summary>Adds a specified number to another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
           <format type="text/markdown">
             <![CDATA[
@@ -1897,9 +1897,9 @@ The following example illustrates addition with complex numbers.
         <Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">The double value to add.</param>
+        <param name="left">The double-precision real value to add.</param>
         <param name="right">The complex value to add.</param>
-        <summary>Adds a double number to a complex number.</summary>
+       <summary>Adds a double-precision real number to a complex number.</summary>
         <returns>The sum of <paramref name="left" /> and <paramref name="right" /> as a complex number.</returns>
         <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Add(System.NDouble,System.Numerics.Complex)" />
@@ -1932,8 +1932,8 @@ The following example illustrates addition with complex numbers.
       </Parameters>
       <Docs>
         <param name="left">The complex value to add.</param>
-        <param name="right">The double value to add.</param>
-        <summary>Adds a complex number to a double number.</summary>
+        <param name="right">The double-precision real value to add.</param>
+        <summary>Adds a complex number to a double-precision real number.</summary>
         <returns>The sum of <paramref name="left" /> and <paramref name="right" /> as a complex number.</returns>
         <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Add(System.Numerics.Complex,System.Double)" />
@@ -1985,7 +1985,7 @@ The following example illustrates addition with complex numbers.
         <AssemblyVersion>4.1.1.0</AssemblyVersion>
       </AssemblyInfo>
       <Docs>
-        <summary>Divides a specified number by another specified number.</summary>
+        <summary>Divides a specified number by another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -2036,9 +2036,9 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Divide%
         <Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">The double value to be divided.</param>
+        <param name="left">The double-precision real value to be divided.</param>
         <param name="right">The complex value to divide by.</param>
-        <summary>Divides a specified double number by a specified complex number.</summary>
+        <summary>Divides a specified double-precision real number by a specified complex number.</summary>
         <returns>The result of dividing <paramref name="left" /> by <paramref name="right" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Divide(System.Double,System.Numerics.Complex)" />
@@ -2071,8 +2071,8 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Divide%
       </Parameters>
       <Docs>
         <param name="left">The complex value to be divided.</param>
-        <param name="right">The double value to divide by.</param>
-        <summary>Divides a specified complex number by a specified double number.</summary>
+        <param name="right">The double-precision real value to divide by.</param>
+        <summary>Divides a specified complex number by a specified double-precision real number.</summary>
         <returns>The result of dividing <paramref name="left" /> by <paramref name="right" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Divide(System.Numerics.Complex,System.Double)" />
@@ -2887,7 +2887,7 @@ This API is not CLS-compliant.</summary>
         <AssemblyVersion>4.1.1.0</AssemblyVersion>
       </AssemblyInfo>
       <Docs>
-        <summary>Multiplies a specified number by another specified number.</summary>
+        <summary>Multiplies a specified number by another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -2938,9 +2938,9 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Multipl
         <Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">The double value to multiply.</param>
+        <param name="left">The double-precision real value to multiply.</param>
         <param name="right">The complex value to multiply.</param>
-        <summary>Multiplies a specified double number by a specified complex number.</summary>
+        <summary>Multiplies a specified double-precision real number by a specified complex number.</summary>
         <returns>The product of <paramref name="left" /> and <paramref name="right" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Multiply(System.Double,System.Numerics.Complex)" />
@@ -2973,8 +2973,8 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Multipl
       </Parameters>
       <Docs>
         <param name="left">The complex value to multiply.</param>
-        <param name="right">The double value to multiply.</param>
-        <summary>Multiplies specified complex number by a specified double number.</summary>
+        <param name="right">The double-precision real value to multiply.</param>
+        <summary>Multiplies the specified complex number by a specified double-precision real number.</summary>
         <returns>The product of <paramref name="left" /> and <paramref name="right" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Multiply(System.Numerics.Complex,System.Double)" />
@@ -3026,7 +3026,7 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Multipl
         <AssemblyVersion>4.1.1.0</AssemblyVersion>
       </AssemblyInfo>
       <Docs>
-        <summary>Substracts a specified number from another specified number.</summary>
+        <summary>Subtracts a specified number from another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -3077,9 +3077,9 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Subtrac
         <Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">The double value to subtract from (the minuend).</param>
+        <param name="left">The double-precision real value to subtract from (the minuend).</param>
         <param name="right">The complex value to subtract (the subtrahend).</param>
-        <summary>Subtracts a complex number from a double number.</summary>
+        <summary>Subtracts a complex number from a double-precision real number.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Subtract(System.Double,System.Numerics.Complex)" />
@@ -3112,8 +3112,8 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Subtrac
       </Parameters>
       <Docs>
         <param name="left">The complex value to subtract from (the minuend).</param>
-        <param name="right">The double value to subtract (the subtrahend).</param>
-        <summary>Subtracts a double number from a complex number.</summary>
+        <param name="right">The double-precision real value to subtract (the subtrahend).</param>
+        <summary>Subtracts a double-precision real number from a complex number.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.Subtract(System.Numerics.Complex,System.Double)" />
@@ -3638,7 +3638,7 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Subtrac
         <AssemblyVersion>4.1.1.0</AssemblyVersion>
       </AssemblyInfo>
       <Docs>
-        <summary>Substracts a specified number from another specified number and returns the result.</summary>
+        <summary>Subtracts a specified number from another specified number, where at least one of them is a complex number, and the other could be a double-precision real number, and returns the result.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -3689,9 +3689,9 @@ The following example subtracts each complex number in an array from a complex n
         <Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="left">The double value to subtract from (the minuend).</param>
+        <param name="left">The double-precision real value to subtract from (the minuend).</param>
         <param name="right">The complex value to subtract (the subtrahend).</param>
-        <summary>Subtracts one complex number from a double number and returns the result.</summary>
+        <summary>Subtracts one complex number from a double-precision real number and returns the result.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.op_Subtraction(System.Double,System.Numerics.Complex)" />
@@ -3724,8 +3724,8 @@ The following example subtracts each complex number in an array from a complex n
       </Parameters>
       <Docs>
         <param name="left">The complex value to subtract from (the minuend).</param>
-        <param name="right">The double value to subtract (the subtrahend).</param>
-        <summary>Subtracts one double number from a complex number and returns the result.</summary>
+        <param name="right">The double-precision real value to subtract (the subtrahend).</param>
+        <summary>Subtracts one double-precision real number from a complex number and returns the result.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
         <remarks>To be added.</remarks>
         <altmember cref="M:System.Numerics.Complex.op_Subtraction(System.Numerics.Complex,System.Double)" />
@@ -4195,4 +4195,4 @@ The following example subtracts each complex number in an array from a complex n
       </Docs>
     </Member>
   </Members>
-</Type>
\ No newline at end of file
+</Type>

From a31a4ad4643f80a0eb7074ac18046d8fcb3b7468 Mon Sep 17 00:00:00 2001
From: carlossanlop <calope@microsoft.com>
Date: Fri, 2 Aug 2019 12:36:00 -0700
Subject: [PATCH 03/10] Add individual remarks, apply suggestions by mairaw,
 Jozkee, tannergooding

---
 xml/System.Numerics/Complex.xml | 342 ++++++++++++++++++++++++++------
 1 file changed, 283 insertions(+), 59 deletions(-)

diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml
index 82652d17b80..fdb5992afea 100644
--- a/xml/System.Numerics/Complex.xml
+++ b/xml/System.Numerics/Complex.xml
@@ -1833,19 +1833,14 @@
       </Docs>
     </Member>
     <MemberGroup MemberName="op_Addition">
-      <AssemblyInfo>
-        <AssemblyName>System.Runtime.Numerics</AssemblyName>
-        <AssemblyVersion>4.1.1.0</AssemblyVersion>
-      </AssemblyInfo>
       <Docs>
         <summary>Adds a specified number to another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
-          <format type="text/markdown">
-            <![CDATA[
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-The <xref:System.Numerics.Complex.op_Addition%2A> method defines the addition operation for complex numbers. It enables code such as the following:
+The <xref:System.Numerics.Complex.op_Addition%2A> operators allow performing addition operations that involve complex numbers. They enable code such as the following:
 
 [!code-csharp[System.Numerics.Complex.Add#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.add/cs/add3.cs#3)]
 [!code-vb[System.Numerics.Complex.Add#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.add/vb/add3.vb#3)]
@@ -1854,15 +1849,21 @@ The addition of a complex number, a + bi, and a second complex number, c + di, t
 
 (a + c) + (b + d)i
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+The addition of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form:
+
+(a + c) + di
+
+The addition of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form:
 
-Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%2A> method instead.
+(a + c) + bi
 
-The equivalent method for this operator is <xref:System.Numerics.Complex.Add%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>.
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%2A> equivalent group of methods instead.
 
 ## Examples
 
-The following example illustrates addition with complex numbers.
+The following example illustrates addition with complex numbers:
 
 [!code-csharp[System.Numerics.Complex.Add#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.add/cs/add2.cs#2)]
 [!code-vb[System.Numerics.Complex.Add#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.add/vb/add2.vb#2)]
@@ -1899,9 +1900,23 @@ The following example illustrates addition with complex numbers.
       <Docs>
         <param name="left">The double-precision real value to add.</param>
         <param name="right">The complex value to add.</param>
-       <summary>Adds a double-precision real number to a complex number.</summary>
+        <summary>Adds a double-precision real number to a complex number.</summary>
         <returns>The sum of <paramref name="left" /> and <paramref name="right" /> as a complex number.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The addition of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form:
+
+(a + c) + di
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Add(System.NDouble,System.Numerics.Complex)" />
       </Docs>
     </Member>
@@ -1935,7 +1950,21 @@ The following example illustrates addition with complex numbers.
         <param name="right">The double-precision real value to add.</param>
         <summary>Adds a complex number to a double-precision real number.</summary>
         <returns>The sum of <paramref name="left" /> and <paramref name="right" /> as a complex number.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The addition of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form:
+
+(a + c) + bi
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Add(System.Numerics.Complex,System.Double)" />
       </Docs>
     </Member>
@@ -1975,15 +2004,25 @@ The following example illustrates addition with complex numbers.
         <param name="right">The second complex value to add.</param>
         <summary>Adds two complex numbers.</summary>
         <returns>The sum of <paramref name="left" /> and <paramref name="right" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The addition of a complex number, a + bi, and a second complex number, c + di, takes the following form:
+
+(a + c) + (b + d)i
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent method instead.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Add(System.Numerics.Complex,System.Numerics.Complex)" />
       </Docs>
     </Member>
     <MemberGroup MemberName="op_Division">
-      <AssemblyInfo>
-        <AssemblyName>System.Runtime.Numerics</AssemblyName>
-        <AssemblyVersion>4.1.1.0</AssemblyVersion>
-      </AssemblyInfo>
       <Docs>
         <summary>Divides a specified number by another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
@@ -1991,7 +2030,7 @@ The following example illustrates addition with complex numbers.
 
 ## Remarks
 
-The <xref:System.Numerics.Complex.op_Division%2A> method defines the division operation for complex numbers. It enables code such as the following:
+The <xref:System.Numerics.Complex.op_Division%2A> operators allow performing division operation that involve complex numbers. They enable code such as the following:
 
 [!code-csharp[System.Numerics.Complex.Divide#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.divide/cs/divide2.cs#2)]
 [!code-vb[System.Numerics.Complex.Divide#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.divide/vb/divide2.vb#2)]
@@ -2000,11 +2039,17 @@ The division of a complex number, a + bi, and a second complex number, c + di, t
 
 ((ac + bd) / (c<sup>2</sup> + d<sup>2</sup>)) + ((bc - ad) / (c<sup>2</sup> + d<sup>2</sup>)i
 
-If the division results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+The division of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form:
 
-Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%2A> method instead.
+(ac / c<sup>2</sup>) + (bc / c<sup>2</sup>)i
 
-The equivalent method for this operator is <xref:System.Numerics.Complex.Divide%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>.
+The division of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form:
+
+(ac / (c<sup>2</sup> + d<sup>2</sup>)) + (ad / (c<sup>2</sup> + d<sup>2</sup>)i
+
+If the division results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%2A> equivalent group of method instead.
 
           ]]></format>
         </remarks>
@@ -2040,7 +2085,21 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Divide%
         <param name="right">The complex value to divide by.</param>
         <summary>Divides a specified double-precision real number by a specified complex number.</summary>
         <returns>The result of dividing <paramref name="left" /> by <paramref name="right" />, as a complex number.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The division of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form:
+
+(ac / (c<sup>2</sup> + d<sup>2</sup>)) + (ad / (c<sup>2</sup> + d<sup>2</sup>)i
+
+If the division results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Divide(System.Double,System.Numerics.Complex)" />
       </Docs>
     </Member>
@@ -2074,7 +2133,21 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Divide%
         <param name="right">The double-precision real value to divide by.</param>
         <summary>Divides a specified complex number by a specified double-precision real number.</summary>
         <returns>The result of dividing <paramref name="left" /> by <paramref name="right" />, as a complex number.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The division of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form:
+
+(ac / c<sup>2</sup>) + (bc / c<sup>2</sup>)i
+
+If the division results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent method instead.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Divide(System.Numerics.Complex,System.Double)" />
       </Docs>
     </Member>
@@ -2114,7 +2187,21 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Divide%
         <param name="right">The complex value to divide by.</param>
         <summary>Divides a specified complex number by another specified complex number.</summary>
         <returns>The result of dividing <paramref name="left" /> by <paramref name="right" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The division of a complex number, a + bi, and a second complex number, c + di, takes the following form:
+
+((ac + bd) / (c<sup>2</sup> + d<sup>2</sup>)) + ((bc - ad) / (c<sup>2</sup> + d<sup>2</sup>)i
+
+If the division results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent method instead.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Divide(System.Numerics.Complex,System.Numerics.Complex)" />
       </Docs>
     </Member>
@@ -2882,10 +2969,6 @@ This API is not CLS-compliant.</summary>
       </Docs>
     </Member>
     <MemberGroup MemberName="op_Multiply">
-      <AssemblyInfo>
-        <AssemblyName>System.Runtime.Numerics</AssemblyName>
-        <AssemblyVersion>4.1.1.0</AssemblyVersion>
-      </AssemblyInfo>
       <Docs>
         <summary>Multiplies a specified number by another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
@@ -2893,7 +2976,7 @@ This API is not CLS-compliant.</summary>
 
 ## Remarks
 
-The <xref:System.Numerics.Complex.op_Multiply%2A> method defines the operation of the multiplication operator for complex numbers. It enables code such as the following:
+The <xref:System.Numerics.Complex.op_Multiply%2A> operators allow performing multiplication operations that involve complex numbers. They enable code such as the following:
 
 [!code-csharp[System.Numerics.Complex.Multiply#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.multiply/cs/multiply2.cs#2)]
 [!code-vb[System.Numerics.Complex.Multiply#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.multiply/vb/multiply2.vb#2)]
@@ -2902,13 +2985,19 @@ The multiplication of a complex number, a + bi, and a second complex number, c +
 
 (ac - bd) + (ad + bc)i
 
-If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+The multiplication of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form:
+
+ac + bci
+
+The multiplication of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form:
 
-Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%2A> method instead.
+ac + adi
 
-The equivalent method for this operator is <xref:System.Numerics.Complex.Multiply%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>]]>.
+If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%2A> equivalent group of methods instead.
 
-          </format>
+          ]]></format>
         </remarks>
       </Docs>
     </MemberGroup>
@@ -2942,7 +3031,21 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Multipl
         <param name="right">The complex value to multiply.</param>
         <summary>Multiplies a specified double-precision real number by a specified complex number.</summary>
         <returns>The product of <paramref name="left" /> and <paramref name="right" />, as a complex number.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The multiplication of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form:
+
+ac + adi
+
+If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Multiply(System.Double,System.Numerics.Complex)" />
       </Docs>
     </Member>
@@ -2976,7 +3079,21 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Multipl
         <param name="right">The double-precision real value to multiply.</param>
         <summary>Multiplies the specified complex number by a specified double-precision real number.</summary>
         <returns>The product of <paramref name="left" /> and <paramref name="right" />, as a complex number.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The multiplication of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form:
+
+ac + bci
+
+If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent method instead.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Multiply(System.Numerics.Complex,System.Double)" />
       </Docs>
     </Member>
@@ -3016,15 +3133,25 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Multipl
         <param name="right">The second complex value to multiply.</param>
         <summary>Multiplies two specified complex numbers.</summary>
         <returns>The product of <paramref name="left" /> and <paramref name="right" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The multiplication of a complex number, a + bi, and a second complex number, c + di, takes the following form:
+
+(ac - bd) + (ad + bc)i
+
+If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Multiply(System.Numerics.Complex,System.Numerics.Complex)" />
       </Docs>
     </Member>
     <MemberGroup MemberName="op_Subtraction">
-      <AssemblyInfo>
-        <AssemblyName>System.Runtime.Numerics</AssemblyName>
-        <AssemblyVersion>4.1.1.0</AssemblyVersion>
-      </AssemblyInfo>
       <Docs>
         <summary>Subtracts a specified number from another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
@@ -3032,20 +3159,26 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Multipl
 
 ## Remarks
 
-The <xref:System.Numerics.Complex.op_Subtraction%2A> method defines the operation of the subtraction operator for complex numbers. It enables code such as the following:
+The <xref:System.Numerics.Complex.op_Subtraction%2A> operators allow performing subtraction operations that involve complex numbers. They enable code such as the following:
 
 [!code-csharp[System.Numerics.Complex.Subtract#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.subtract/cs/subtract2.cs#2)]
 [!code-vb[System.Numerics.Complex.Subtract#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.subtract/vb/subtract2.vb#2)]
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form:
 
 (a - c) + (b - d)i
 
-Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%2A> method instead.
+The subtraction of a real number (which can be regarded as the complex number c + 0i) from a complex number (a + bi) takes the following form:
+
+(a - c) + bi
+
+The subtraction of a complex number (c + di) from a real number (which can be regarded as the complex number a + 0i) takes the following form:
 
-The equivalent method for this operator is <xref:System.Numerics.Complex.Subtract%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType>.
+(a - c) - di
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%2A> equivalent group of methods instead.
  
           ]]></format>
         </remarks>
@@ -3081,7 +3214,21 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Subtrac
         <param name="right">The complex value to subtract (the subtrahend).</param>
         <summary>Subtracts a complex number from a double-precision real number.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The subtraction of a complex number (c + di) from a real number (which can be regarded as the complex number a + 0i) takes the following form:
+
+(a - c) - di
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> method instead.
+ 
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Subtract(System.Double,System.Numerics.Complex)" />
       </Docs>
     </Member>
@@ -3115,7 +3262,21 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Subtrac
         <param name="right">The double-precision real value to subtract (the subtrahend).</param>
         <summary>Subtracts a double-precision real number from a complex number.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The subtraction of a real number (which can be regarded as the complex number c + 0i) from a complex number (a + bi) takes the following form:
+
+(a - c) + bi
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> method instead.
+ 
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Subtract(System.Numerics.Complex,System.Double)" />
       </Docs>
     </Member>
@@ -3155,7 +3316,21 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Subtrac
         <param name="right">The value to subtract (the subtrahend).</param>
         <summary>Subtracts a complex number from another complex number.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form:
+
+(a - c) + (b - d)i
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> method instead.
+ 
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.Subtract(System.Numerics.Complex,System.Numerics.Complex)" />
       </Docs>
     </Member>
@@ -3633,10 +3808,6 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Subtrac
       </Docs>
     </Member>
     <MemberGroup MemberName="Subtract">
-      <AssemblyInfo>
-        <AssemblyName>System.Runtime.Numerics</AssemblyName>
-        <AssemblyVersion>4.1.1.0</AssemblyVersion>
-      </AssemblyInfo>
       <Docs>
         <summary>Subtracts a specified number from another specified number, where at least one of them is a complex number, and the other could be a double-precision real number, and returns the result.</summary>
         <remarks>
@@ -3644,17 +3815,28 @@ The equivalent method for this operator is <xref:System.Numerics.Complex.Subtrac
 
 ## Remarks
 
+The <xref:System.Numerics.Complex.Substract%2A> methods allow performing subtraction operations that involve complex numbers.
+
+
 The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form:
 
 (a - c) + (b - d)i
 
+The subtraction of a real number (which can be regarded as the complex number c + 0i) from a complex number (a + bi) takes the following form:
+
+(a - c) + bi
+
+The subtraction of a complex number (c + di) from a real number (which can be regarded as the complex number a + 0i) takes the following form:
+
+(a - c) - di
+
 If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
-Languages that do not support custom operators can use the <xref:System.Numerics.Complex.Subtract%2A> method to perform subtraction using complex numbers.
+Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%2A> equivalent group of operators too.
 
 ## Examples
 
-The following example subtracts each complex number in an array from a complex number.
+The following example subtracts each complex number in an array from a complex number:
 
 [!code-csharp[System.Numerics.Complex.Subtract#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.subtract/cs/subtract1.cs#1)]
 [!code-vb[System.Numerics.Complex.Subtract#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.subtract/vb/subtract1.vb#1)]
@@ -3693,7 +3875,21 @@ The following example subtracts each complex number in an array from a complex n
         <param name="right">The complex value to subtract (the subtrahend).</param>
         <summary>Subtracts one complex number from a double-precision real number and returns the result.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The subtraction of a complex number (c + di) from a real number (which can be regarded as the complex number a + 0i) takes the following form:
+
+(a - c) - di
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent operator too.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.op_Subtraction(System.Double,System.Numerics.Complex)" />
       </Docs>
     </Member>
@@ -3727,7 +3923,21 @@ The following example subtracts each complex number in an array from a complex n
         <param name="right">The double-precision real value to subtract (the subtrahend).</param>
         <summary>Subtracts one double-precision real number from a complex number and returns the result.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />, as a complex number.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The subtraction of a real number (which can be regarded as the complex number c + 0i) from a complex number (a + bi) takes the following form:
+
+(a - c) + bi
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent operator too.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.op_Subtraction(System.Numerics.Complex,System.Double)" />
       </Docs>
     </Member>
@@ -3772,7 +3982,21 @@ The following example subtracts each complex number in an array from a complex n
         <param name="right">The value to subtract (the subtrahend).</param>
         <summary>Subtracts one complex number from another and returns the result.</summary>
         <returns>The result of subtracting <paramref name="right" /> from <paramref name="left" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form:
+
+(a - c) + (b - d)i
+
+If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+
+Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent operator too.
+
+          ]]></format>
+        </remarks>
         <altmember cref="M:System.Numerics.Complex.op_Subtraction(System.Numerics.Complex,System.Numerics.Complex)" />
       </Docs>
     </Member>

From 5355a9826f81ef0f6944ba38b5effee1182061da Mon Sep 17 00:00:00 2001
From: carlossanlop <calope@microsoft.com>
Date: Fri, 2 Aug 2019 12:39:58 -0700
Subject: [PATCH 04/10] Method -> operation name

---
 xml/System.Numerics/Complex.xml | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml
index fdb5992afea..e7278fc9cd1 100644
--- a/xml/System.Numerics/Complex.xml
+++ b/xml/System.Numerics/Complex.xml
@@ -1857,7 +1857,7 @@ The addition of a complex number (a + bi) and a real number (which can be regard
 
 (a + c) + bi
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the addition results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%2A> equivalent group of methods instead.
 
@@ -1911,7 +1911,7 @@ The addition of a real number (which can be regarded as the complex number a + 0
 
 (a + c) + di
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the addition results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
 
@@ -1959,7 +1959,7 @@ The addition of a complex number (a + bi) and a real number (which can be regard
 
 (a + c) + bi
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the addition results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
 
@@ -2013,7 +2013,7 @@ The addition of a complex number, a + bi, and a second complex number, c + di, t
 
 (a + c) + (b + d)i
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the addition results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent method instead.
 
@@ -3176,7 +3176,7 @@ The subtraction of a complex number (c + di) from a real number (which can be re
 
 (a - c) - di
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%2A> equivalent group of methods instead.
  
@@ -3223,7 +3223,7 @@ The subtraction of a complex number (c + di) from a real number (which can be re
 
 (a - c) - di
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> method instead.
  
@@ -3271,7 +3271,7 @@ The subtraction of a real number (which can be regarded as the complex number c
 
 (a - c) + bi
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> method instead.
  
@@ -3325,7 +3325,7 @@ The subtraction of a complex number, c + di, from another complex number, a + bi
 
 (a - c) + (b - d)i
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> method instead.
  
@@ -3830,7 +3830,7 @@ The subtraction of a complex number (c + di) from a real number (which can be re
 
 (a - c) - di
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%2A> equivalent group of operators too.
 
@@ -3884,7 +3884,7 @@ The subtraction of a complex number (c + di) from a real number (which can be re
 
 (a - c) - di
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent operator too.
 
@@ -3932,7 +3932,7 @@ The subtraction of a real number (which can be regarded as the complex number c
 
 (a - c) + bi
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent operator too.
 
@@ -3991,7 +3991,7 @@ The subtraction of a complex number, c + di, from another complex number, a + bi
 
 (a - c) + (b - d)i
 
-If the method call results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent operator too.
 

From eeee6a39cabb2b90b367a31f76af4e745824cc52 Mon Sep 17 00:00:00 2001
From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com>
Date: Mon, 5 Aug 2019 09:49:52 -0700
Subject: [PATCH 05/10] suggestions by rpetrusha and Jozkee

Co-Authored-By: David Cantu <jozkyy@gmail.com>
Co-Authored-By: Ron Petrusha <ronpet@microsoft.com>
---
 xml/System.Numerics/Complex.xml | 34 ++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml
index e7278fc9cd1..7015d8b174f 100644
--- a/xml/System.Numerics/Complex.xml
+++ b/xml/System.Numerics/Complex.xml
@@ -1840,7 +1840,7 @@
 
 ## Remarks
 
-The <xref:System.Numerics.Complex.op_Addition%2A> operators allow performing addition operations that involve complex numbers. They enable code such as the following:
+The <xref:System.Numerics.Complex.op_Addition%2A> operator allows performing addition operations that involve complex numbers. It enables code such as the following:
 
 [!code-csharp[System.Numerics.Complex.Add#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.add/cs/add3.cs#3)]
 [!code-vb[System.Numerics.Complex.Add#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.add/vb/add3.vb#3)]
@@ -2030,7 +2030,7 @@ Languages that do not support custom operators can call the <xref:System.Numeric
 
 ## Remarks
 
-The <xref:System.Numerics.Complex.op_Division%2A> operators allow performing division operation that involve complex numbers. They enable code such as the following:
+The <xref:System.Numerics.Complex.op_Division%2A> operator allows performing division operations that involve complex numbers. It enables code such as the following:
 
 [!code-csharp[System.Numerics.Complex.Divide#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.divide/cs/divide2.cs#2)]
 [!code-vb[System.Numerics.Complex.Divide#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.divide/vb/divide2.vb#2)]
@@ -2976,7 +2976,7 @@ This API is not CLS-compliant.</summary>
 
 ## Remarks
 
-The <xref:System.Numerics.Complex.op_Multiply%2A> operators allow performing multiplication operations that involve complex numbers. They enable code such as the following:
+The <xref:System.Numerics.Complex.op_Multiply%2A> operator allows performing multiplication operations that involve complex numbers. It enables code such as the following:
 
 [!code-csharp[System.Numerics.Complex.Multiply#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.multiply/cs/multiply2.cs#2)]
 [!code-vb[System.Numerics.Complex.Multiply#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.multiply/vb/multiply2.vb#2)]
@@ -3159,7 +3159,7 @@ Languages that do not support custom operators can call the <xref:System.Numeric
 
 ## Remarks
 
-The <xref:System.Numerics.Complex.op_Subtraction%2A> operators allow performing subtraction operations that involve complex numbers. They enable code such as the following:
+The <xref:System.Numerics.Complex.op_Subtraction%2A> operator allows performing subtraction operations that involve complex numbers. It enables code such as the following:
 
 [!code-csharp[System.Numerics.Complex.Subtract#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.subtract/cs/subtract2.cs#2)]
 [!code-vb[System.Numerics.Complex.Subtract#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.subtract/vb/subtract2.vb#2)]
@@ -3176,7 +3176,7 @@ The subtraction of a complex number (c + di) from a real number (which can be re
 
 (a - c) - di
 
-If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%2A> equivalent group of methods instead.
  
@@ -3223,7 +3223,7 @@ The subtraction of a complex number (c + di) from a real number (which can be re
 
 (a - c) - di
 
-If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> method instead.
  
@@ -3271,7 +3271,7 @@ The subtraction of a real number (which can be regarded as the complex number c
 
 (a - c) + bi
 
-If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> method instead.
  
@@ -3325,7 +3325,7 @@ The subtraction of a complex number, c + di, from another complex number, a + bi
 
 (a - c) + (b - d)i
 
-If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> method instead.
  
@@ -3815,7 +3815,7 @@ Languages that do not support custom operators can call the <xref:System.Numeric
 
 ## Remarks
 
-The <xref:System.Numerics.Complex.Substract%2A> methods allow performing subtraction operations that involve complex numbers.
+The <xref:System.Numerics.Complex.Subtract%2A> method allows subtraction operations that involve complex numbers.
 
 
 The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form:
@@ -3830,9 +3830,9 @@ The subtraction of a complex number (c + di) from a real number (which can be re
 
 (a - c) - di
 
-If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
-Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%2A> equivalent group of operators too.
+Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Subtraction%2A> equivalent group of operators too.
 
 ## Examples
 
@@ -3884,9 +3884,9 @@ The subtraction of a complex number (c + di) from a real number (which can be re
 
 (a - c) - di
 
-If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
-Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent operator too.
+Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Subtraction%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent operator too.
 
           ]]></format>
         </remarks>
@@ -3932,9 +3932,9 @@ The subtraction of a real number (which can be regarded as the complex number c
 
 (a - c) + bi
 
-If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
-Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent operator too.
+Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Subtraction%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent operator too.
 
           ]]></format>
         </remarks>
@@ -3991,9 +3991,9 @@ The subtraction of a complex number, c + di, from another complex number, a + bi
 
 (a - c) + (b - d)i
 
-If the substraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
+If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
-Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Substraction%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent operator too.
+Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Subtraction%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent operator too.
 
           ]]></format>
         </remarks>

From d9a4e2be43d7f8870f09587b56695abed2120606 Mon Sep 17 00:00:00 2001
From: carlossanlop <calope@microsoft.com>
Date: Mon, 5 Aug 2019 09:56:24 -0700
Subject: [PATCH 06/10] suggestions by rpetrusha and Jozkee

---
 xml/System.Numerics/Complex.xml | 91 ---------------------------------
 1 file changed, 91 deletions(-)

diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml
index 7015d8b174f..89e8fb979ca 100644
--- a/xml/System.Numerics/Complex.xml
+++ b/xml/System.Numerics/Complex.xml
@@ -1845,18 +1845,6 @@ The <xref:System.Numerics.Complex.op_Addition%2A> operator allows performing add
 [!code-csharp[System.Numerics.Complex.Add#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.add/cs/add3.cs#3)]
 [!code-vb[System.Numerics.Complex.Add#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.add/vb/add3.vb#3)]
 
-The addition of a complex number, a + bi, and a second complex number, c + di, takes the following form:
-
-(a + c) + (b + d)i
-
-The addition of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form:
-
-(a + c) + di
-
-The addition of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form:
-
-(a + c) + bi
-
 If the addition results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%2A> equivalent group of methods instead.
@@ -1911,8 +1899,6 @@ The addition of a real number (which can be regarded as the complex number a + 0
 
 (a + c) + di
 
-If the addition results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
 
           ]]></format>
@@ -1959,8 +1945,6 @@ The addition of a complex number (a + bi) and a real number (which can be regard
 
 (a + c) + bi
 
-If the addition results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
 
           ]]></format>
@@ -2013,8 +1997,6 @@ The addition of a complex number, a + bi, and a second complex number, c + di, t
 
 (a + c) + (b + d)i
 
-If the addition results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent method instead.
 
           ]]></format>
@@ -2035,18 +2017,6 @@ The <xref:System.Numerics.Complex.op_Division%2A> operator allows performing div
 [!code-csharp[System.Numerics.Complex.Divide#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.divide/cs/divide2.cs#2)]
 [!code-vb[System.Numerics.Complex.Divide#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.divide/vb/divide2.vb#2)]
 
-The division of a complex number, a + bi, and a second complex number, c + di, takes the following form:
-
-((ac + bd) / (c<sup>2</sup> + d<sup>2</sup>)) + ((bc - ad) / (c<sup>2</sup> + d<sup>2</sup>)i
-
-The division of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form:
-
-(ac / c<sup>2</sup>) + (bc / c<sup>2</sup>)i
-
-The division of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form:
-
-(ac / (c<sup>2</sup> + d<sup>2</sup>)) + (ad / (c<sup>2</sup> + d<sup>2</sup>)i
-
 If the division results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%2A> equivalent group of method instead.
@@ -2094,8 +2064,6 @@ The division of a real number (which can be regarded as the complex number a + 0
 
 (ac / (c<sup>2</sup> + d<sup>2</sup>)) + (ad / (c<sup>2</sup> + d<sup>2</sup>)i
 
-If the division results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
 
           ]]></format>
@@ -2142,8 +2110,6 @@ The division of a complex number (a + bi) and a real number (which can be regard
 
 (ac / c<sup>2</sup>) + (bc / c<sup>2</sup>)i
 
-If the division results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent method instead.
 
           ]]></format>
@@ -2196,8 +2162,6 @@ The division of a complex number, a + bi, and a second complex number, c + di, t
 
 ((ac + bd) / (c<sup>2</sup> + d<sup>2</sup>)) + ((bc - ad) / (c<sup>2</sup> + d<sup>2</sup>)i
 
-If the division results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent method instead.
 
           ]]></format>
@@ -2981,18 +2945,6 @@ The <xref:System.Numerics.Complex.op_Multiply%2A> operator allows performing mul
 [!code-csharp[System.Numerics.Complex.Multiply#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.multiply/cs/multiply2.cs#2)]
 [!code-vb[System.Numerics.Complex.Multiply#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.multiply/vb/multiply2.vb#2)]
 
-The multiplication of a complex number, a + bi, and a second complex number, c + di, takes the following form:
-
-(ac - bd) + (ad + bc)i
-
-The multiplication of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form:
-
-ac + bci
-
-The multiplication of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form:
-
-ac + adi
-
 If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%2A> equivalent group of methods instead.
@@ -3040,8 +2992,6 @@ The multiplication of a real number (which can be regarded as the complex number
 
 ac + adi
 
-If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
 
           ]]></format>
@@ -3088,8 +3038,6 @@ The multiplication of a complex number (a + bi) and a real number (which can be
 
 ac + bci
 
-If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent method instead.
 
           ]]></format>
@@ -3142,8 +3090,6 @@ The multiplication of a complex number, a + bi, and a second complex number, c +
 
 (ac - bd) + (ad + bc)i
 
-If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
 
           ]]></format>
@@ -3164,18 +3110,6 @@ The <xref:System.Numerics.Complex.op_Subtraction%2A> operator allows performing
 [!code-csharp[System.Numerics.Complex.Subtract#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.subtract/cs/subtract2.cs#2)]
 [!code-vb[System.Numerics.Complex.Subtract#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.subtract/vb/subtract2.vb#2)]
 
-The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form:
-
-(a - c) + (b - d)i
-
-The subtraction of a real number (which can be regarded as the complex number c + 0i) from a complex number (a + bi) takes the following form:
-
-(a - c) + bi
-
-The subtraction of a complex number (c + di) from a real number (which can be regarded as the complex number a + 0i) takes the following form:
-
-(a - c) - di
-
 If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%2A> equivalent group of methods instead.
@@ -3223,8 +3157,6 @@ The subtraction of a complex number (c + di) from a real number (which can be re
 
 (a - c) - di
 
-If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> method instead.
  
           ]]></format>
@@ -3271,8 +3203,6 @@ The subtraction of a real number (which can be regarded as the complex number c
 
 (a - c) + bi
 
-If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> method instead.
  
           ]]></format>
@@ -3325,8 +3255,6 @@ The subtraction of a complex number, c + di, from another complex number, a + bi
 
 (a - c) + (b - d)i
 
-If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> method instead.
  
           ]]></format>
@@ -3817,19 +3745,6 @@ Languages that do not support custom operators can call the <xref:System.Numeric
 
 The <xref:System.Numerics.Complex.Subtract%2A> method allows subtraction operations that involve complex numbers.
 
-
-The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form:
-
-(a - c) + (b - d)i
-
-The subtraction of a real number (which can be regarded as the complex number c + 0i) from a complex number (a + bi) takes the following form:
-
-(a - c) + bi
-
-The subtraction of a complex number (c + di) from a real number (which can be regarded as the complex number a + 0i) takes the following form:
-
-(a - c) - di
-
 If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Subtraction%2A> equivalent group of operators too.
@@ -3884,8 +3799,6 @@ The subtraction of a complex number (c + di) from a real number (which can be re
 
 (a - c) - di
 
-If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Subtraction%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent operator too.
 
           ]]></format>
@@ -3932,8 +3845,6 @@ The subtraction of a real number (which can be regarded as the complex number c
 
 (a - c) + bi
 
-If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Subtraction%28System.Numerics.Complex%2CSystem.Double%29?displayProperty=nameWithType> equivalent operator too.
 
           ]]></format>
@@ -3991,8 +3902,6 @@ The subtraction of a complex number, c + di, from another complex number, a + bi
 
 (a - c) + (b - d)i
 
-If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
-
 Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Subtraction%28System.Numerics.Complex%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent operator too.
 
           ]]></format>

From d192f32d4fe05ac11308e0a42b2ebcde61d34ec9 Mon Sep 17 00:00:00 2001
From: carlossanlop <calope@microsoft.com>
Date: Mon, 5 Aug 2019 11:22:55 -0700
Subject: [PATCH 07/10] Tables with efficiency gain

---
 xml/System.Numerics/Complex.xml | 55 +++++++++++++++++++++++++++++----
 1 file changed, 49 insertions(+), 6 deletions(-)

diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml
index 89e8fb979ca..d476983d535 100644
--- a/xml/System.Numerics/Complex.xml
+++ b/xml/System.Numerics/Complex.xml
@@ -1836,7 +1836,8 @@
       <Docs>
         <summary>Adds a specified number to another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[
+          <format type="text/markdown">
+  <![CDATA[
 
 ## Remarks
 
@@ -1849,6 +1850,13 @@ If the addition results in an overflow in either the real or imaginary component
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%2A> equivalent group of methods instead.
 
+The <xref:System.Numerics.Complex.op_Addition%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
+
+| Operator           | Cost    |
+|--------------------|---------|
+| Complex + Complex  | 2 flops |
+| Complex + double<br />-or-<br />double + Complex | 1 flop  |
+
 ## Examples
 
 The following example illustrates addition with complex numbers:
@@ -2008,7 +2016,8 @@ Languages that do not support custom operators can call the <xref:System.Numeric
       <Docs>
         <summary>Divides a specified number by another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[
+          <format type="text/markdown">
+  <![CDATA[
 
 ## Remarks
 
@@ -2021,6 +2030,14 @@ If the division results in an overflow in either the real or imaginary component
 
 Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%2A> equivalent group of method instead.
 
+The <xref:System.Numerics.Complex.op_Division%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
+
+| Operator          | Cost                              |
+|-------------------|-----------------------------------|
+| Complex / Complex | 9 flops                           |
+| Complex / double  | 2 flops (largest efficiency gain) |
+| double / Complex  | 6 flops                           |
+
           ]]></format>
         </remarks>
       </Docs>
@@ -2936,7 +2953,8 @@ This API is not CLS-compliant.</summary>
       <Docs>
         <summary>Multiplies a specified number by another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[
+          <format type="text/markdown">
+  <![CDATA[
 
 ## Remarks
 
@@ -2949,6 +2967,13 @@ If the multiplication results in an overflow in either the real or imaginary com
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%2A> equivalent group of methods instead.
 
+The <xref:System.Numerics.Complex.op_Multiply%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
+
+| Operator          | Cost    |
+|-------------------|---------|
+| Complex * Complex | 6 flops |
+| Complex * double<br />-or-<br />double * Complex | 2 flops  |
+
           ]]></format>
         </remarks>
       </Docs>
@@ -2994,6 +3019,8 @@ ac + adi
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
 
+There are implicit casts from double -> Complex, so it's currently possible to write e.g. 2.5 * z for Complex z, but in addition to the cast, this costs 6 flops for a Complex * Complex multiply, while it's possible to implement a double * Complex multiply directly in 2 flops.
+
           ]]></format>
         </remarks>
         <altmember cref="M:System.Numerics.Complex.Multiply(System.Double,System.Numerics.Complex)" />
@@ -3101,7 +3128,8 @@ Languages that do not support custom operators can call the <xref:System.Numeric
       <Docs>
         <summary>Subtracts a specified number from another specified number, where at least one of them is a complex number, and the other could be a double-precision real number.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[
+          <format type="text/markdown">
+  <![CDATA[
 
 ## Remarks
 
@@ -3113,7 +3141,14 @@ The <xref:System.Numerics.Complex.op_Subtraction%2A> operator allows performing
 If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%2A> equivalent group of methods instead.
- 
+
+The <xref:System.Numerics.Complex.op_Addition%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
+
+| Operator          | Cost    |
+|-------------------|---------|
+| Complex + Complex | 2 flops |
+| Complex + double<br />-or-<br />double + Complex | 1 flop  |
+
           ]]></format>
         </remarks>
       </Docs>
@@ -3739,7 +3774,8 @@ Languages that do not support custom operators can call the <xref:System.Numeric
       <Docs>
         <summary>Subtracts a specified number from another specified number, where at least one of them is a complex number, and the other could be a double-precision real number, and returns the result.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[
+          <format type="text/markdown">
+  <![CDATA[
 
 ## Remarks
 
@@ -3749,6 +3785,13 @@ If the subtraction results in an overflow in either the real or imaginary compon
 
 Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Subtraction%2A> equivalent group of operators too.
 
+The <xref:System.Numerics.Complex.Subtract%2A> methods that receive one double are more efficient than the method that receive two Complex numbers:
+
+| Operator          | Cost    |
+|-------------------|---------|
+| Complex - Complex | 2 flops |
+| Complex - double<br />-or-<br />double - Complex | 1 flop  |
+
 ## Examples
 
 The following example subtracts each complex number in an array from a complex number:

From dc43aa42175f1c9fc90d29bb62b5e26d3d74969d Mon Sep 17 00:00:00 2001
From: carlossanlop <calope@microsoft.com>
Date: Mon, 5 Aug 2019 11:27:23 -0700
Subject: [PATCH 08/10] operator -> operation

---
 xml/System.Numerics/Complex.xml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml
index d476983d535..f8d6416c049 100644
--- a/xml/System.Numerics/Complex.xml
+++ b/xml/System.Numerics/Complex.xml
@@ -1852,7 +1852,7 @@ Languages that do not support custom operators can call the <xref:System.Numeric
 
 The <xref:System.Numerics.Complex.op_Addition%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
 
-| Operator           | Cost    |
+| Operation          | Cost    |
 |--------------------|---------|
 | Complex + Complex  | 2 flops |
 | Complex + double<br />-or-<br />double + Complex | 1 flop  |
@@ -2032,7 +2032,7 @@ Languages that do not support custom operators and operator overloading can call
 
 The <xref:System.Numerics.Complex.op_Division%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
 
-| Operator          | Cost                              |
+| Operation         | Cost                              |
 |-------------------|-----------------------------------|
 | Complex / Complex | 9 flops                           |
 | Complex / double  | 2 flops (largest efficiency gain) |
@@ -2969,7 +2969,7 @@ Languages that do not support custom operators can call the <xref:System.Numeric
 
 The <xref:System.Numerics.Complex.op_Multiply%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
 
-| Operator          | Cost    |
+| Operation         | Cost    |
 |-------------------|---------|
 | Complex * Complex | 6 flops |
 | Complex * double<br />-or-<br />double * Complex | 2 flops  |
@@ -3144,7 +3144,7 @@ Languages that do not support custom operators can call the <xref:System.Numeric
 
 The <xref:System.Numerics.Complex.op_Addition%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
 
-| Operator          | Cost    |
+| Operation         | Cost    |
 |-------------------|---------|
 | Complex + Complex | 2 flops |
 | Complex + double<br />-or-<br />double + Complex | 1 flop  |
@@ -3787,7 +3787,7 @@ Languages that support custom operators can use the <xref:System.Numerics.Comple
 
 The <xref:System.Numerics.Complex.Subtract%2A> methods that receive one double are more efficient than the method that receive two Complex numbers:
 
-| Operator          | Cost    |
+| Operation         | Cost    |
 |-------------------|---------|
 | Complex - Complex | 2 flops |
 | Complex - double<br />-or-<br />double - Complex | 1 flop  |

From 3912a42bf805b05a003eef2420aced10ce7db285 Mon Sep 17 00:00:00 2001
From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com>
Date: Mon, 5 Aug 2019 18:32:01 -0700
Subject: [PATCH 09/10] Remove cost tables

---
 xml/System.Numerics/Complex.xml | 36 +++++----------------------------
 1 file changed, 5 insertions(+), 31 deletions(-)

diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml
index f8d6416c049..1d3f92fd326 100644
--- a/xml/System.Numerics/Complex.xml
+++ b/xml/System.Numerics/Complex.xml
@@ -1850,12 +1850,7 @@ If the addition results in an overflow in either the real or imaginary component
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Add%2A> equivalent group of methods instead.
 
-The <xref:System.Numerics.Complex.op_Addition%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
-
-| Operation          | Cost    |
-|--------------------|---------|
-| Complex + Complex  | 2 flops |
-| Complex + double<br />-or-<br />double + Complex | 1 flop  |
+The <xref:System.Numerics.Complex.op_Addition%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers.
 
 ## Examples
 
@@ -2030,13 +2025,7 @@ If the division results in an overflow in either the real or imaginary component
 
 Languages that do not support custom operators and operator overloading can call the <xref:System.Numerics.Complex.Divide%2A> equivalent group of method instead.
 
-The <xref:System.Numerics.Complex.op_Division%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
-
-| Operation         | Cost                              |
-|-------------------|-----------------------------------|
-| Complex / Complex | 9 flops                           |
-| Complex / double  | 2 flops (largest efficiency gain) |
-| double / Complex  | 6 flops                           |
+The <xref:System.Numerics.Complex.op_Division%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers.
 
           ]]></format>
         </remarks>
@@ -2967,12 +2956,7 @@ If the multiplication results in an overflow in either the real or imaginary com
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%2A> equivalent group of methods instead.
 
-The <xref:System.Numerics.Complex.op_Multiply%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
-
-| Operation         | Cost    |
-|-------------------|---------|
-| Complex * Complex | 6 flops |
-| Complex * double<br />-or-<br />double * Complex | 2 flops  |
+The <xref:System.Numerics.Complex.op_Multiply%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers.
 
           ]]></format>
         </remarks>
@@ -3142,12 +3126,7 @@ If the subtraction results in an overflow in either the real or imaginary compon
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Subtract%2A> equivalent group of methods instead.
 
-The <xref:System.Numerics.Complex.op_Addition%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers:
-
-| Operation         | Cost    |
-|-------------------|---------|
-| Complex + Complex | 2 flops |
-| Complex + double<br />-or-<br />double + Complex | 1 flop  |
+The <xref:System.Numerics.Complex.op_Addition%2A> operators that receive one double are more efficient than the operators that receive two Complex numbers.
 
           ]]></format>
         </remarks>
@@ -3785,12 +3764,7 @@ If the subtraction results in an overflow in either the real or imaginary compon
 
 Languages that support custom operators can use the <xref:System.Numerics.Complex.op_Subtraction%2A> equivalent group of operators too.
 
-The <xref:System.Numerics.Complex.Subtract%2A> methods that receive one double are more efficient than the method that receive two Complex numbers:
-
-| Operation         | Cost    |
-|-------------------|---------|
-| Complex - Complex | 2 flops |
-| Complex - double<br />-or-<br />double - Complex | 1 flop  |
+The <xref:System.Numerics.Complex.Subtract%2A> methods that receive one double are more efficient than the method that receive two Complex numbers.
 
 ## Examples
 

From f2317a65ac8239806ac1b1caec4072a5afc8a349 Mon Sep 17 00:00:00 2001
From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com>
Date: Tue, 6 Aug 2019 09:29:47 -0700
Subject: [PATCH 10/10] remove unnecessary comment

---
 xml/System.Numerics/Complex.xml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml
index 1d3f92fd326..1764baa24bb 100644
--- a/xml/System.Numerics/Complex.xml
+++ b/xml/System.Numerics/Complex.xml
@@ -3003,7 +3003,6 @@ ac + adi
 
 Languages that do not support custom operators can call the <xref:System.Numerics.Complex.Multiply%28System.Double%2CSystem.Numerics.Complex%29?displayProperty=nameWithType> equivalent method instead.
 
-There are implicit casts from double -> Complex, so it's currently possible to write e.g. 2.5 * z for Complex z, but in addition to the cast, this costs 6 flops for a Complex * Complex multiply, while it's possible to implement a double * Complex multiply directly in 2 flops.
 
           ]]></format>
         </remarks>