Skip to content

Commit 7afedf0

Browse files
Gnbrkm41tannergooding
authored and
carlossanlop
committed
Update System.Numerics.Vector<T> documents (#3334)
* Update System.Numerics.Vector documents * Emphasise that this type is not appropriate for general purpose vector operations * Update ctor remarks so that only primitive numeric types are allowed * Update ctor remarks so that only the first `Vector<T>.Count` elements are added to the vector (for Span/Array overloads) * Add information about exception that can be thrown when array.Length < Vector<T>.Count Related: https://github.com/dotnet/corefx/issues/23448 * Apply suggestions * Pull the type constraint to the top of the ctor docs since it's shared throughout, list out the types for future-proofing * Update param descriptions for array/spans to be explicit about the remainders Part of dotnet-api-docs/#3334 Co-Authored-By: Tanner Gooding <[email protected]> * Use see tag * Reference the type instead of just writing it out * Define the meaning of primitive numeric data type * Pluralise "instance" Co-authored-by: Tanner Gooding <[email protected]>
1 parent e082ee5 commit 7afedf0

File tree

1 file changed

+92
-25
lines changed

1 file changed

+92
-25
lines changed

‎xml/System.Numerics/Vector`1.xml

Lines changed: 92 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -49,11 +49,11 @@
4949
<format type="text/markdown"><![CDATA[
5050
5151
## Remarks
52-
<xref:System.Numerics.Vector%601> is an immutable structure that represents a single vector of a specified numeric type. The count of a <xref:System.Numerics.Vector%601> instance is fixed, but its upper limit is CPU-register dependent. It is intended to be used as a building block for vectorizing large algorithms.
52+
<xref:System.Numerics.Vector%601> is an immutable structure that represents a single vector of a specified numeric type. The count of <xref:System.Numerics.Vector%601> instances is fixed, but its upper limit is CPU-register dependent. It is intended to be used as a building block for vectorizing large algorithms, and therefore cannot be used directly as an arbitrary length vector or tensor.
5353
54-
The <xref:System.Numerics.Vector%601> structure provides support for hardware acceleration.
54+
The <xref:System.Numerics.Vector%601> structure provides support for hardware acceleration.
5555
56-
The following table shows which primitive numeric data type and operation combination uses intrinsic instructions for faster executions:
56+
The term 'primitive numeric data type' in this document refers to numeric data types that are directly supported by the CPU and have instructions that can manipulate those data types. The following table shows which primitive numeric data type and operation combination uses intrinsic instructions for faster executions:
5757
5858
| Primitive type | `+` | `-` | `*` | `/` |
5959
| --- | :---: | :---: | :---: | :---: |
@@ -72,6 +72,48 @@
7272
</remarks>
7373
</Docs>
7474
<Members>
75+
<MemberGroup MemberName=".ctor">
76+
<AssemblyInfo>
77+
<AssemblyName>System.Numerics.Vectors</AssemblyName>
78+
<AssemblyVersion>2.0.5.0</AssemblyVersion>
79+
<AssemblyVersion>4.0.0.0</AssemblyVersion>
80+
<AssemblyVersion>4.1.0.0</AssemblyVersion>
81+
<AssemblyVersion>4.1.1.0</AssemblyVersion>
82+
<AssemblyVersion>4.1.2.0</AssemblyVersion>
83+
<AssemblyVersion>4.1.3.0</AssemblyVersion>
84+
<AssemblyVersion>4.1.4.0</AssemblyVersion>
85+
<AssemblyVersion>4.1.5.0</AssemblyVersion>
86+
</AssemblyInfo>
87+
<AssemblyInfo>
88+
<AssemblyName>netstandard</AssemblyName>
89+
<AssemblyVersion>2.0.0.0</AssemblyVersion>
90+
<AssemblyVersion>2.1.0.0</AssemblyVersion>
91+
</AssemblyInfo>
92+
<Docs>
93+
<summary>Creates an instance of <see cref="T:System.Numerics.Vector`1" />.</summary>
94+
<remarks>
95+
<format type="text/markdown"><![CDATA[
96+
97+
The type `T` can be any of the following numeric types:
98+
99+
| C# keywords | Framework Type |
100+
| ----------- | -------------------- |
101+
| `sbyte` | <xref:System.SByte> |
102+
| `byte` | <xref:System.Byte> |
103+
| `short` | <xref:System.Int16> |
104+
| `ushort` | <xref:System.UInt16> |
105+
| `int` | <xref:System.Int32> |
106+
| `uint` | <xref:System.UInt32> |
107+
| `long` | <xref:System.Int64> |
108+
| `ulong` | <xref:System.UInt64> |
109+
| `float` | <xref:System.Single> |
110+
| `double` | <xref:System.Double> |
111+
112+
]]>
113+
</format>
114+
</remarks>
115+
</Docs>
116+
</MemberGroup>
75117
<Member MemberName=".ctor">
76118
<MemberSignature Language="C#" Value="public Vector (ReadOnlySpan&lt;byte&gt; values);" />
77119
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(valuetype System.ReadOnlySpan`1&lt;unsigned int8&gt; values) cil managed" />
@@ -92,9 +134,19 @@
92134
<Parameter Name="values" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-3.0;netcore-3.1" />
93135
</Parameters>
94136
<Docs>
95-
<param name="values">A read-only span of bytes that contains the values to add to the vector. The span must contain at least <see cref="P:System.Numerics.Vector`1.Count" /> elements.</param>
137+
<param name="values">A read-only span of bytes that contains the values to add to the vector. The span must contain at least <see cref="P:System.Numerics.Vector`1.Count" /> elements and only the first <see cref="P:System.Numerics.Vector`1.Count" /> elements are used.</param>
96138
<summary>Constructs a vector from the given read-only span of bytes.</summary>
97-
<remarks>To be added.</remarks>
139+
<remarks>
140+
<format type="text/markdown"><![CDATA[
141+
142+
## Remarks
143+
144+
Only the first <xref:System.Numerics.Vector%601.Count%2A> elements are added to the vector. The remainders are ignored.
145+
146+
]]></format>
147+
</remarks>
148+
<exception cref="T:System.IndexOutOfRangeException">
149+
<paramref name="values" /> did not contain at least <see cref="P:System.Numerics.Vector`1.Count" /> elements.</exception>
98150
</Docs>
99151
</Member>
100152
<Member MemberName=".ctor">
@@ -117,9 +169,19 @@
117169
<Parameter Name="values" Type="System.ReadOnlySpan&lt;T&gt;" Index="0" FrameworkAlternate="netcore-3.0;netcore-3.1" />
118170
</Parameters>
119171
<Docs>
120-
<param name="values">The values to add to the vector, as a read-only span of objects of type T. The span must contain at least <see cref="P:System.Numerics.Vector`1.Count" /> elements.</param>
172+
<param name="values">The values to add to the vector, as a read-only span of objects of type T. The span must contain at least <see cref="P:System.Numerics.Vector`1.Count" /> elements and only the first <see cref="P:System.Numerics.Vector`1.Count" /> elements are used.</param>
121173
<summary>Constructs a vector from the given <see cref="T:System.ReadOnlySpan`1" />.</summary>
122-
<remarks>To be added.</remarks>
174+
<remarks>
175+
<format type="text/markdown"><![CDATA[
176+
177+
## Remarks
178+
179+
Only the first <xref:System.Numerics.Vector%601.Count%2A> elements are added to the vector. The remainders are ignored.
180+
181+
]]></format>
182+
</remarks>
183+
<exception cref="T:System.IndexOutOfRangeException">
184+
<paramref name="values" /> did not contain at least <see cref="P:System.Numerics.Vector`1.Count" /> elements.</exception>
123185
</Docs>
124186
</Member>
125187
<Member MemberName=".ctor">
@@ -145,9 +207,19 @@
145207
<Parameter Name="values" Type="System.Span&lt;T&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1" />
146208
</Parameters>
147209
<Docs>
148-
<param name="values">The values to add to the vector, as a span of objects of type T. The span must contain at least <see cref="P:System.Numerics.Vector`1.Count" /> elements.</param>
210+
<param name="values">The values to add to the vector, as a span of objects of type T. The span must contain at least <see cref="P:System.Numerics.Vector`1.Count" /> elements and only the first <see cref="P:System.Numerics.Vector`1.Count" /> elements are used.</param>
149211
<summary>Constructs a vector from the given <see cref="T:System.Span`1" />.</summary>
150-
<remarks>To be added.</remarks>
212+
<remarks>
213+
<format type="text/markdown"><![CDATA[
214+
215+
## Remarks
216+
217+
Only the first <xref:System.Numerics.Vector%601.Count%2A> elements are added to the vector. The remainders are ignored.
218+
219+
]]></format>
220+
</remarks>
221+
<exception cref="T:System.IndexOutOfRangeException">
222+
<paramref name="values" /> did not contain at least <see cref="P:System.Numerics.Vector`1.Count" /> elements.</exception>
151223
</Docs>
152224
</Member>
153225
<Member MemberName=".ctor">
@@ -181,14 +253,7 @@
181253
<Docs>
182254
<param name="value">The numeric type that defines the type of the components in the vector.</param>
183255
<summary>Creates a vector whose components are of a specified type.</summary>
184-
<remarks>
185-
<format type="text/markdown"><![CDATA[
186-
187-
## Remarks
188-
`value` can be any primitive numeric type (that is, a numeric type whose <xref:System.Type.IsPrimitive%2A?displayProperty=nameWithType> property returns `true`.
189-
190-
]]></format>
191-
</remarks>
256+
<remarks>To be added. </remarks>
192257
</Docs>
193258
</Member>
194259
<Member MemberName=".ctor">
@@ -220,13 +285,14 @@
220285
<Parameter Name="values" Type="T[]" />
221286
</Parameters>
222287
<Docs>
223-
<param name="values">A numeric array.</param>
288+
<param name="values">The values to add to the vector, as an array of objects of type T. The array must contain at least <see cref="P:System.Numerics.Vector`1.Count" /> elements and only the first <see cref="P:System.Numerics.Vector`1.Count" /> elements are used.</param>
224289
<summary>Creates a vector from a specified array.</summary>
225290
<remarks>
226291
<format type="text/markdown"><![CDATA[
227292
228293
## Remarks
229-
`values` must contain at least <xref:System.Numerics.Vector%601.Count%2A> elements.
294+
295+
Only the first <xref:System.Numerics.Vector%601.Count%2A> elements are added to the vector. The remainders are ignored.
230296
231297
]]></format>
232298
</remarks>
@@ -264,16 +330,17 @@
264330
<Parameter Name="index" Type="System.Int32" />
265331
</Parameters>
266332
<Docs>
267-
<param name="values">A numeric array.</param>
333+
<param name="values">The values to add to the vector, as an array of objects of type T. The array must contain at least <see cref="P:System.Numerics.Vector`1.Count" /> elements from the specified index and only the first <see cref="P:System.Numerics.Vector`1.Count" /> elements are used.</param>
268334
<param name="index">The starting index position from which to create the vector.</param>
269335
<summary>Creates a vector from a specified array starting at a specified index position.</summary>
270336
<remarks>
271-
<format type="text/markdown"><![CDATA[
272-
337+
<format type="text/markdown"><![CDATA[
338+
273339
## Remarks
274-
The array must contain at least <xref:System.Numerics.Vector%601.Count%2A?displayProperty=nameWithType> elements from the specified index.
275-
276-
]]></format>
340+
341+
Only the first <xref:System.Numerics.Vector%601.Count%2A> elements are added to the vector. The remainders are ignored.
342+
343+
]]></format>
277344
</remarks>
278345
<exception cref="T:System.ArgumentNullException">
279346
<paramref name="values" /> is <see langword="null" />.</exception>

0 commit comments

Comments
 (0)