Skip to content

Commit 1d823f1

Browse files
jozkeemairaw
jozkee
authored and
mairaw
committed
Added documentation for System.Numerics.Complex APIs targeted for 3.0 (#2946)
* Adding documentation for System.Numerics APIs. * Fixing typo missed in #2912 * Fixing syntax errors.
1 parent 57cbbf1 commit 1d823f1

File tree

1 file changed

+178
-79
lines changed

1 file changed

+178
-79
lines changed

‎xml/System.Numerics/Complex.xml

Lines changed: 178 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -314,6 +314,31 @@
314314
<altmember cref="M:System.Math.Acos(System.Double)" />
315315
</Docs>
316316
</Member>
317+
<MemberGroup MemberName="Add">
318+
<Docs>
319+
<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>
320+
<remarks>
321+
<format type="text/markdown"><![CDATA[
322+
323+
## Remarks
324+
The <xref:System.Numerics.Complex.Add%2A> methods allow performing addition operations that involve complex numbers.
325+
326+
If the method call results in an overflow in either the real or imaginary component, the value of the component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
327+
328+
Languages that do not support custom operators can use the <xref:System.Numerics.Complex.Add%2A> method to perform addition with complex numbers.
329+
330+
The <xref:System.Numerics.Complex.Add%2A> methods that receive one double are more efficient than the methods that receive two complex numbers.
331+
332+
## Examples
333+
334+
The following example illustrates addition with complex numbers.
335+
336+
[!code-csharp[System.Numerics.Complex.Add#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.add/cs/add1.cs#1)]
337+
[!code-vb[System.Numerics.Complex.Add#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.add/vb/add1.vb#1)]
338+
]]></format>
339+
</remarks>
340+
</Docs>
341+
</MemberGroup>
317342
<Member MemberName="Add">
318343
<MemberSignature Language="C#" Value="public static System.Numerics.Complex Add (double left, System.Numerics.Complex right);" />
319344
<MemberSignature Language="ILAsm" Value=".method public static hidebysig valuetype System.Numerics.Complex Add(float64 left, valuetype System.Numerics.Complex right) cil managed" />
@@ -340,11 +365,19 @@
340365
<Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
341366
</Parameters>
342367
<Docs>
343-
<param name="left">To be added.</param>
344-
<param name="right">To be added.</param>
345-
<summary>To be added.</summary>
346-
<returns>To be added.</returns>
347-
<remarks>To be added.</remarks>
368+
<param name="left">The double-precision real value to add.</param>
369+
<param name="right">The complex value to add.</param>
370+
<summary>Adds a double-precision real number to a complex number and returns the result.</summary>
371+
<returns>The sum of <paramref name="left" /> and <paramref name="right" />.</returns>
372+
<remarks>
373+
<format type="text/markdown"><![CDATA[
374+
## Remarks
375+
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:
376+
377+
(a + c) + di
378+
]]></format>
379+
</remarks>
380+
<altmember cref="M:System.Numerics.Complex.op_Addition(System.Double,System.Numerics.Complex)" />
348381
</Docs>
349382
</Member>
350383
<Member MemberName="Add">
@@ -373,11 +406,19 @@
373406
<Parameter Name="right" Type="System.Double" Index="1" FrameworkAlternate="netcore-3.0" />
374407
</Parameters>
375408
<Docs>
376-
<param name="left">To be added.</param>
377-
<param name="right">To be added.</param>
378-
<summary>To be added.</summary>
379-
<returns>To be added.</returns>
380-
<remarks>To be added.</remarks>
409+
<param name="left">The complex value to add.</param>
410+
<param name="right">The double-precision real value to add.</param>
411+
<summary>Adds a complex number to a double-precision real number and returns the result.</summary>
412+
<returns>The sum of <paramref name="left" /> and <paramref name="right" />.</returns>
413+
<remarks>
414+
<format type="text/markdown"><![CDATA[
415+
## Remarks
416+
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:
417+
418+
(a + c) + bi
419+
]]></format>
420+
</remarks>
421+
<altmember cref="M:System.Numerics.Complex.op_Addition(System.Numerics.Complex,System.Double)" />
381422
</Docs>
382423
</Member>
383424
<Member MemberName="Add">
@@ -428,18 +469,7 @@
428469
The addition of a complex number, a + bi, and a second complex number, c + di, takes the following form:
429470
430471
(a + c) + (b + d)i.
431-
432-
If the method call results in an overflow in either the real or imaginary component, the value of the component is either <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType>.
433-
434-
Languages that do not support custom operators can use the <xref:System.Numerics.Complex.Add%2A> method to perform addition with complex numbers.
435-
436-
437-
438-
## Examples
439-
The following example illustrates addition with complex numbers.
440-
441-
[!code-csharp[System.Numerics.Complex.Add#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.add/cs/add1.cs#1)]
442-
[!code-vb[System.Numerics.Complex.Add#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.add/vb/add1.vb#1)]
472+
443473
444474
]]></format>
445475
</remarks>
@@ -721,6 +751,31 @@
721751
<altmember cref="M:System.Math.Cosh(System.Double)" />
722752
</Docs>
723753
</Member>
754+
<MemberGroup MemberName="Divide">
755+
<Docs>
756+
<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>
757+
<remarks>
758+
<format type="text/markdown"><![CDATA[
759+
760+
## Remarks
761+
The <xref:System.Numerics.Complex.Divide%2A> methods allow performing division operations that involve complex numbers.
762+
763+
If the calculation of the quotient 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>.
764+
765+
The <xref:System.Numerics.Complex.Divide%2A> method can be used by languages that do not support custom operators. Its behavior is identical to division using the division operator.
766+
767+
The <xref:System.Numerics.Complex.Divide%2A> methods that receive one double are more efficient than the methods that receive two complex numbers.
768+
769+
## Examples
770+
The following example divides a complex number by each element in an array of complex numbers.
771+
772+
[!code-csharp[System.Numerics.Complex.Divide#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.divide/cs/divide1.cs#1)]
773+
[!code-vb[System.Numerics.Complex.Divide#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.divide/vb/divide1.vb#1)]
774+
775+
]]></format>
776+
</remarks>
777+
</Docs>
778+
</MemberGroup>
724779
<Member MemberName="Divide">
725780
<MemberSignature Language="C#" Value="public static System.Numerics.Complex Divide (double dividend, System.Numerics.Complex divisor);" />
726781
<MemberSignature Language="ILAsm" Value=".method public static hidebysig valuetype System.Numerics.Complex Divide(float64 dividend, valuetype System.Numerics.Complex divisor) cil managed" />
@@ -747,11 +802,22 @@
747802
<Parameter Name="divisor" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
748803
</Parameters>
749804
<Docs>
750-
<param name="dividend">To be added.</param>
751-
<param name="divisor">To be added.</param>
752-
<summary>To be added.</summary>
753-
<returns>To be added.</returns>
754-
<remarks>To be added.</remarks>
805+
<param name="dividend">The double-precision real number to be divided.</param>
806+
<param name="divisor">The complex number to divide by.</param>
807+
<summary>Divides one double-precision real number by a complex number and returns the result.</summary>
808+
<returns>The quotient of the division.</returns>
809+
<remarks>
810+
<format type="text/markdown"><![CDATA[
811+
812+
## Remarks
813+
814+
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:
815+
816+
(ac / (c<sup>2</sup> + d<sup>2</sup>)) + (ad / (c<sup>2</sup> + d<sup>2</sup>)i
817+
818+
]]></format>
819+
</remarks>
820+
<altmember cref="M:System.Numerics.Complex.op_Division(System.Double,System.Numerics.Complex)" />
755821
</Docs>
756822
</Member>
757823
<Member MemberName="Divide">
@@ -780,11 +846,22 @@
780846
<Parameter Name="divisor" Type="System.Double" Index="1" FrameworkAlternate="netcore-3.0" />
781847
</Parameters>
782848
<Docs>
783-
<param name="dividend">To be added.</param>
784-
<param name="divisor">To be added.</param>
785-
<summary>To be added.</summary>
786-
<returns>To be added.</returns>
787-
<remarks>To be added.</remarks>
849+
<param name="dividend">The complex number to be divided.</param>
850+
<param name="divisor">The double-precision real number to divide by.</param>
851+
<summary>Divides one complex number by a double-precision real number and returns the result.</summary>
852+
<returns>The quotient of the division.</returns>
853+
<remarks>
854+
<format type="text/markdown"><![CDATA[
855+
856+
## Remarks
857+
858+
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:
859+
860+
(ac / c<sup>2</sup>) + (bc / c<sup>2</sup>)i
861+
862+
]]></format>
863+
</remarks>
864+
<altmember cref="M:System.Numerics.Complex.op_Division(System.Numerics.Complex,System.Double)" />
788865
</Docs>
789866
</Member>
790867
<Member MemberName="Divide">
@@ -835,19 +912,7 @@
835912
The division of a complex number, a + bi, by a second complex number, number, c + di, takes the following form:
836913
837914
((ac + bd) / (c<sup>2</sup> + d<sup>2</sup>)) + ((bc - ad) / (c<sup>2</sup> + d<sup>2</sup>)i
838-
839-
If the calculation of the quotient 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>.
840-
841-
The <xref:System.Numerics.Complex.Divide%2A> method can be used by languages that do not support custom operators. Its behavior is identical to division using the division operator.
842-
843-
844-
845-
## Examples
846-
The following example divides a complex number by each element in an array of complex numbers.
847-
848-
[!code-csharp[System.Numerics.Complex.Divide#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.divide/cs/divide1.cs#1)]
849-
[!code-vb[System.Numerics.Complex.Divide#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.divide/vb/divide1.vb#1)]
850-
915+
851916
]]></format>
852917
</remarks>
853918
<altmember cref="M:System.Numerics.Complex.op_Division(System.Numerics.Complex,System.Numerics.Complex)" />
@@ -1261,7 +1326,7 @@
12611326
<ReturnType>System.Numerics.Complex</ReturnType>
12621327
</ReturnValue>
12631328
<Docs>
1264-
<summary>To be added.</summary>
1329+
<summary>Represents infinity as a complex number.</summary>
12651330
<remarks>To be added.</remarks>
12661331
</Docs>
12671332
</Member>
@@ -1290,9 +1355,9 @@
12901355
<Parameter Name="value" Type="System.Numerics.Complex" Index="0" FrameworkAlternate="netcore-3.0" />
12911356
</Parameters>
12921357
<Docs>
1293-
<param name="value">To be added.</param>
1294-
<summary>To be added.</summary>
1295-
<returns>To be added.</returns>
1358+
<param name="value">A complex number.</param>
1359+
<summary>Determines whether the specified complex number is finite.</summary>
1360+
<returns><see langword="true" /> if both, the real and imaginary parts are finite (zero, subnormal or normal); otherwise, <see langword="false" />.</returns>
12961361
<remarks>To be added.</remarks>
12971362
</Docs>
12981363
</Member>
@@ -1321,9 +1386,9 @@
13211386
<Parameter Name="value" Type="System.Numerics.Complex" Index="0" FrameworkAlternate="netcore-3.0" />
13221387
</Parameters>
13231388
<Docs>
1324-
<param name="value">To be added.</param>
1325-
<summary>To be added.</summary>
1326-
<returns>To be added.</returns>
1389+
<param name="value">A complex number.</param>
1390+
<summary>Returns a value indicating whether the specified complex number evaluates to infinity.</summary>
1391+
<returns><see langword="true"/> if either, the real or imaginary part are <see cref="F:System.Double.PositiveInfinity" /> or <see cref="F:System.Double.NegativeInfinity" />; otherwise, <see langword="false"/>.</returns>
13271392
<remarks>To be added.</remarks>
13281393
</Docs>
13291394
</Member>
@@ -1352,9 +1417,9 @@
13521417
<Parameter Name="value" Type="System.Numerics.Complex" Index="0" FrameworkAlternate="netcore-3.0" />
13531418
</Parameters>
13541419
<Docs>
1355-
<param name="value">To be added.</param>
1356-
<summary>To be added.</summary>
1357-
<returns>To be added.</returns>
1420+
<param name="value">A complex number.</param>
1421+
<summary>Returns a value that indicates whether the specified complex instance is not a number (NaN).</summary>
1422+
<returns><see langword="true"/> if the specified value is not finite nor infinite; otherwise, <see langword="false"/>.</returns>
13581423
<remarks>To be added.</remarks>
13591424
</Docs>
13601425
</Member>
@@ -1570,6 +1635,32 @@
15701635
<altmember cref="P:System.Numerics.Complex.Phase" />
15711636
</Docs>
15721637
</Member>
1638+
<MemberGroup MemberName="op_Multiply">
1639+
<Docs>
1640+
<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>
1641+
<remarks>
1642+
<format type="text/markdown">
1643+
<![CDATA[
1644+
1645+
## Remarks
1646+
1647+
The <xref:System.Numerics.Complex.Multiply%2A> methods allow performing multiplication operations that involve complex numbers.
1648+
1649+
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>.
1650+
1651+
The <xref:System.Numerics.Complex.Multiply%2A> method is implemented for languages that do not support custom operators. Its behavior is identical to multiplication using the multiplication operator.
1652+
1653+
1654+
## Examples
1655+
The following example multiples a complex number by each element in an array of complex numbers.
1656+
1657+
[!code-csharp[System.Numerics.Complex.Multiply#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.multiply/cs/multiply1.cs#1)]
1658+
[!code-vb[System.Numerics.Complex.Multiply#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.multiply/vb/multiply1.vb#1)]
1659+
1660+
]]></format>
1661+
</remarks>
1662+
</Docs>
1663+
</MemberGroup>
15731664
<Member MemberName="Multiply">
15741665
<MemberSignature Language="C#" Value="public static System.Numerics.Complex Multiply (double left, System.Numerics.Complex right);" />
15751666
<MemberSignature Language="ILAsm" Value=".method public static hidebysig valuetype System.Numerics.Complex Multiply(float64 left, valuetype System.Numerics.Complex right) cil managed" />
@@ -1596,11 +1687,21 @@
15961687
<Parameter Name="right" Type="System.Numerics.Complex" Index="1" FrameworkAlternate="netcore-3.0" />
15971688
</Parameters>
15981689
<Docs>
1599-
<param name="left">To be added.</param>
1600-
<param name="right">To be added.</param>
1601-
<summary>To be added.</summary>
1602-
<returns>To be added.</returns>
1603-
<remarks>To be added.</remarks>
1690+
<param name="left">The double-precision real number to multiply.</param>
1691+
<param name="right">The complex number to multiply.</param>
1692+
<summary>Returns the product of a double-precision real number and a complex number.</summary>
1693+
<returns>The product of the <paramref name="left" /> and <paramref name="right" /> parameters.</returns>
1694+
<remarks>
1695+
<format type="text/markdown"><![CDATA[
1696+
1697+
## Remarks
1698+
1699+
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:
1700+
1701+
ac + adi
1702+
]]></format>
1703+
</remarks>
1704+
<altmember cref="M:System.Numerics.Complex.op_Multiply(System.Double,System.Numerics.Complex)" />
16041705
</Docs>
16051706
</Member>
16061707
<Member MemberName="Multiply">
@@ -1629,11 +1730,21 @@
16291730
<Parameter Name="right" Type="System.Double" Index="1" FrameworkAlternate="netcore-3.0" />
16301731
</Parameters>
16311732
<Docs>
1632-
<param name="left">To be added.</param>
1633-
<param name="right">To be added.</param>
1634-
<summary>To be added.</summary>
1635-
<returns>To be added.</returns>
1636-
<remarks>To be added.</remarks>
1733+
<param name="left">The complex number to multiply.</param>
1734+
<param name="right">The double-precision real number to multiply.</param>
1735+
<summary>Returns the product of a complex number and a double-precision real number.</summary>
1736+
<returns>The product of the <paramref name="left" /> and <paramref name="right" /> parameters.</returns>
1737+
<remarks>
1738+
<format type="text/markdown"><![CDATA[
1739+
1740+
## Remarks
1741+
1742+
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:
1743+
1744+
ac + bci
1745+
]]></format>
1746+
</remarks>
1747+
<altmember cref="M:System.Numerics.Complex.op_Multiply(System.Numerics.Complex,System.Double)" />
16371748
</Docs>
16381749
</Member>
16391750
<Member MemberName="Multiply">
@@ -1685,18 +1796,6 @@
16851796
16861797
(ac - bd) + (ad + bc)i
16871798
1688-
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>.
1689-
1690-
The <xref:System.Numerics.Complex.Multiply%2A> method is implemented for languages that do not support custom operators. Its behavior is identical to multiplication using the multiplication operator.
1691-
1692-
1693-
1694-
## Examples
1695-
The following example multiples a complex number by each element in an array of complex numbers.
1696-
1697-
[!code-csharp[System.Numerics.Complex.Multiply#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.multiply/cs/multiply1.cs#1)]
1698-
[!code-vb[System.Numerics.Complex.Multiply#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.multiply/vb/multiply1.vb#1)]
1699-
17001799
]]></format>
17011800
</remarks>
17021801
<altmember cref="M:System.Numerics.Complex.op_Multiply(System.Numerics.Complex,System.Numerics.Complex)" />
@@ -1724,7 +1823,7 @@
17241823
<ReturnType>System.Numerics.Complex</ReturnType>
17251824
</ReturnValue>
17261825
<Docs>
1727-
<summary>To be added.</summary>
1826+
<summary>Represents a complex instance that is not a number (NaN).</summary>
17281827
<remarks>To be added.</remarks>
17291828
</Docs>
17301829
</Member>
@@ -1906,7 +2005,7 @@ Languages that do not support custom operators can call the <xref:System.Numeric
19062005
19072006
]]></format>
19082007
</remarks>
1909-
<altmember cref="M:System.Numerics.Complex.Add(System.NDouble,System.Numerics.Complex)" />
2008+
<altmember cref="M:System.Numerics.Complex.Add(System.Double,System.Numerics.Complex)" />
19102009
</Docs>
19112010
</Member>
19122011
<Member MemberName="op_Addition">

0 commit comments

Comments
 (0)