Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit c53cd6f

Browse files
authored
Document System.ArraySegment and its enumerator (dotnet#3556)
1 parent 9103e74 commit c53cd6f

File tree

2 files changed

+90
-31
lines changed

2 files changed

+90
-31
lines changed

xml/System/ArraySegment`1+Enumerator.xml

Lines changed: 52 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,22 @@
3232
</Interface>
3333
</Interfaces>
3434
<Docs>
35-
<summary>To be added.</summary>
36-
<remarks>To be added.</remarks>
35+
<summary>Provides an enumerator for the elements of an <see cref="T:System.ArraySegment`1" />.</summary>
36+
<remarks>
37+
<format type="text/markdown"><![CDATA[
38+
39+
## Remarks
40+
41+
The C# [foreach](~/docs/csharp/language-reference/keywords/foreach-in.md) of the C# language and the [For Each...Next](~/docs/visual-basic/language-reference/statements/for-each-next-statement.md) construct in Visual Basic hides the complexity of enumerators. Instead of directly manipulating the enumerator, using `foreach` or `For Each...Next` is recommended.
42+
43+
Initially, the enumerator is positioned before the first element in the <xref:System.ArraySegment%601>. At this position, <xref:System.ArraySegment%601.Enumerator.Current> is undefined. You must call <xref:System.ArraySegment%601.Enumerator.MoveNext%2A> to advance the enumerator to the first item in the <xref:System.ArraySegment%601> before reading the value of <xref:System.ArraySegment%601.Enumerator.Current>.
44+
45+
<xref:System.ArraySegment%601.Enumerator.Current> returns the same value until <xref:System.ArraySegment%601.Enumerator.MoveNext%2A> is called. <xref:System.ArraySegment%601.Enumerator.MoveNext%2A> sets <xref:System.ArraySegment%601.Enumerator.Current> to the next item in the <xref:System.ArraySegment%601>.
46+
47+
If <xref:System.ArraySegment%601.Enumerator.MoveNext%2A> passes the end of the <xref:System.ArraySegment%601>, <xref:System.ArraySegment%601.Enumerator.MoveNext%2A> returns `false`. When the enumerator is at this state, subsequent calls to <xref:System.ArraySegment%601.Enumerator.MoveNext%2A> also return `false` and <xref:System.ArraySegment%601.Enumerator.Current> is undefined. You cannot set <xref:System.ArraySegment%601.Enumerator.Current> to the first item in the <xref:System.ArraySegment%601> again; you must create a new enumerator instance instead.
48+
49+
]]></format>
50+
</remarks>
3751
</Docs>
3852
<Members>
3953
<Member MemberName="Current">
@@ -60,9 +74,23 @@
6074
<ReturnType>T</ReturnType>
6175
</ReturnValue>
6276
<Docs>
63-
<summary>To be added.</summary>
64-
<value>To be added.</value>
65-
<remarks>To be added.</remarks>
77+
<summary>Gets a reference to the item at the current position of the enumerator.</summary>
78+
<value>The element of the <see cref="T:System.ArraySegment`1" /> at the current position of the enumerator.</value>
79+
<remarks>
80+
<format type="text/markdown"><![CDATA[
81+
82+
## Remarks
83+
84+
`Current` is undefined under either of the following conditions:
85+
86+
- Immediately after the enumerator is created, the enumerator is positioned before the first element in the array segment. <xref:System.ArraySegment%601.Enumerator.MoveNext%2A> must be called to advance the enumerator to the first element of the array segment before reading the value of `Current`.
87+
88+
- The last call to <xref:System.ArraySegment%601.Enumerator.MoveNext%2A> returned `false`, which indicates the end of the array segment.
89+
90+
`Current` returns the same value until <xref:System.ArraySegment%601.Enumerator.MoveNext%2A> is called. <xref:System.ArraySegment%601.Enumerator.MoveNext%2A> sets `Current` to the next item in the array segment.
91+
92+
]]></format>
93+
</remarks>
6694
</Docs>
6795
</Member>
6896
<Member MemberName="Dispose">
@@ -90,7 +118,7 @@
90118
</ReturnValue>
91119
<Parameters />
92120
<Docs>
93-
<summary>To be added.</summary>
121+
<summary>Releases all resources used by this enumerator instance.</summary>
94122
<remarks>To be added.</remarks>
95123
</Docs>
96124
</Member>
@@ -119,9 +147,20 @@
119147
</ReturnValue>
120148
<Parameters />
121149
<Docs>
122-
<summary>To be added.</summary>
123-
<returns>To be added.</returns>
124-
<remarks>To be added.</remarks>
150+
<summary>Advances the enumerator to the next element of the <see cref="T:System.ArraySegment`1" />.</summary>
151+
<returns>
152+
<see langword="true" /> if the enumerator was successfully advanced to the next element; <see langword="false" /> if the enumerator has passed the end of the array segment.</returns>
153+
<remarks>
154+
<format type="text/markdown"><![CDATA[
155+
156+
## Remarks
157+
158+
After an enumerator is created, it is positioned before the first element in the array segment, and the first call to `MoveNext` advances the enumerator to the first item in the array segment.
159+
160+
If `MoveNext` passes the end of the array segment, `MoveNext` returns `false`. When the enumerator is at this state, subsequent calls to `MoveNext` also return `false`.
161+
162+
]]></format>
163+
</remarks>
125164
</Docs>
126165
</Member>
127166
<Member MemberName="System.Collections.IEnumerator.Current">
@@ -148,9 +187,10 @@
148187
<ReturnType>System.Object</ReturnType>
149188
</ReturnValue>
150189
<Docs>
151-
<summary>To be added.</summary>
152-
<value>To be added.</value>
190+
<summary>Gets the element at the current position of the enumerator.</summary>
191+
<value>The element in the array segment at the current position of the enumerator.</value>
153192
<remarks>To be added.</remarks>
193+
<exception cref="T:System.InvalidOperationException">The enumerator is positioned before the first element of the array segment or after the last element.</exception>
154194
</Docs>
155195
</Member>
156196
<Member MemberName="System.Collections.IEnumerator.Reset">
@@ -177,7 +217,7 @@
177217
</ReturnValue>
178218
<Parameters />
179219
<Docs>
180-
<summary>To be added.</summary>
220+
<summary>Sets the enumerator to its initial position, which is before the first element in the array segment.</summary>
181221
<remarks>To be added.</remarks>
182222
</Docs>
183223
</Member>

xml/System/ArraySegment`1.xml

Lines changed: 38 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -331,9 +331,16 @@
331331
<Parameter Name="destination" Type="System.ArraySegment&lt;T&gt;" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
332332
</Parameters>
333333
<Docs>
334-
<param name="destination">To be added.</param>
335-
<summary>To be added.</summary>
334+
<param name="destination">The array segment into which the contents of this instance will be copied.</param>
335+
<summary>Copies the contents of this instance into the specified destination array segment of the same type <typeparamref name="T" />.</summary>
336336
<remarks>To be added.</remarks>
337+
<exception cref="T:System.InvalidOperationException">The underlying array of this instance is <see langword="null" />.
338+
339+
-or-
340+
341+
The underlying array of <paramref name="destination" /> is <paramref name="null" />.
342+
</exception>
343+
<exception cref="T:System.ArgumentException">The length of the underlying array of this instance is larger than the length of the underlying array of <paramref name="destination" />.</exception>
337344
</Docs>
338345
</Member>
339346
<Member MemberName="CopyTo">
@@ -363,9 +370,10 @@
363370
<Parameter Name="destination" Type="T[]" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
364371
</Parameters>
365372
<Docs>
366-
<param name="destination">To be added.</param>
367-
<summary>To be added.</summary>
373+
<param name="destination">The array of type <paramref name="T" /> into which the contents of this instance will be copied.</param>
374+
<summary>Copies the contents of this instance into the specified destination array of the same type <typeparamref name="T" />.</summary>
368375
<remarks>To be added.</remarks>
376+
<exception cref="T:System.InvalidOperationException">The underlying array of this instance is <see langword="null" />.</exception>
369377
</Docs>
370378
</Member>
371379
<Member MemberName="CopyTo">
@@ -402,10 +410,11 @@
402410
<Parameter Name="destinationIndex" Type="System.Int32" Index="1" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
403411
</Parameters>
404412
<Docs>
405-
<param name="destination">To be added.</param>
406-
<param name="destinationIndex">To be added.</param>
407-
<summary>To be added.</summary>
413+
<param name="destination">The array of type <paramref name="T" /> into which the contents of this instance will be copied.</param>
414+
<param name="destinationIndex">The index in <paramref name="destination" /> at which storing begins.</param>
415+
<summary>Copies the contents of this instance into the specified destination array of the same type <typeparamref name="T" />, starting at the specified destination index.</summary>
408416
<remarks>To be added.</remarks>
417+
<exception cref="T:System.InvalidOperationException">The underlying array of this instance is <see langword="null" />.</exception>
409418
</Docs>
410419
</Member>
411420
<Member MemberName="Count">
@@ -486,8 +495,8 @@
486495
<ReturnType>System.ArraySegment&lt;T&gt;</ReturnType>
487496
</ReturnValue>
488497
<Docs>
489-
<summary>To be added.</summary>
490-
<value>To be added.</value>
498+
<summary>Represents the empty array segment. This field is read-only.</summary>
499+
<value>An array segment of type <typeparamref name="T" /> containing zero elements.</value>
491500
<remarks>To be added.</remarks>
492501
</Docs>
493502
</Member>
@@ -855,9 +864,9 @@
855864
<Parameter Name="array" Type="T[]" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
856865
</Parameters>
857866
<Docs>
858-
<param name="array">To be added.</param>
859-
<summary>To be added.</summary>
860-
<returns>To be added.</returns>
867+
<param name="array">The array to convert.</param>
868+
<summary>Defines an implicit conversion of an array of type <typeparamref name="T" /> to an array segment of type <typeparamref name="T" />.</summary>
869+
<returns>An array segment representation of the array.</returns>
861870
<remarks>To be added.</remarks>
862871
</Docs>
863872
</Member>
@@ -945,10 +954,13 @@
945954
<Parameter Name="index" Type="System.Int32" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
946955
</Parameters>
947956
<Docs>
948-
<param name="index">To be added.</param>
949-
<summary>To be added.</summary>
950-
<returns>To be added.</returns>
957+
<param name="index">The index at which to begin the slice.</param>
958+
<summary>Forms a slice out of the current array segment starting at the specified index.</summary>
959+
<returns>An array segment that consists of all elements of the current array segment from <paramref name="index" /> to the end of the array segment.</returns>
951960
<remarks>To be added.</remarks>
961+
<exception cref="T:System.InvalidOperationException">The underlying array of this instance is <see langword="null" />.</exception>
962+
<exception cref="T:System.ArgumentOutOfRangeException">
963+
<paramref name="index" /> is greater than the length of the underlying array of this instance.</exception>
952964
</Docs>
953965
</Member>
954966
<Member MemberName="Slice">
@@ -979,11 +991,18 @@
979991
<Parameter Name="count" Type="System.Int32" Index="1" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
980992
</Parameters>
981993
<Docs>
982-
<param name="index">To be added.</param>
983-
<param name="count">To be added.</param>
984-
<summary>To be added.</summary>
985-
<returns>To be added.</returns>
994+
<param name="index">The index at which to begin the slice.</param>
995+
<param name="count">The desired length of the slice.</param>
996+
<summary>Forms a slice of the specified length out of the current array segment starting at the specified index.</summary>
997+
<returns>An array segment of <paramref name="count" /> elements starting at <paramref name="index" />.</returns>
986998
<remarks>To be added.</remarks>
999+
<exception cref="T:System.InvalidOperationException">The underlying array of this instance is <see langword="null" />.</exception>
1000+
<exception cref="T:System.ArgumentOutOfRangeException">
1001+
<paramref name="index" /> is greater than the length of the underlying array of this instance.
1002+
1003+
-or-
1004+
1005+
<paramref name="count" /> is greater than the length of the underlying array of this instance - <paramref name="index" />.</exception>
9871006
</Docs>
9881007
</Member>
9891008
<Member MemberName="System.Collections.Generic.ICollection&lt;T&gt;.Add">

0 commit comments

Comments
 (0)