Skip to content

Commit 0c4992a

Browse files
gewarrengewarren
committed
reset range and index
1 parent cffca83 commit 0c4992a

File tree

2 files changed

+90
-58
lines changed

2 files changed

+90
-58
lines changed

‎xml/System/Index.xml

Lines changed: 52 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -54,13 +54,21 @@
5454
</Attribute>
5555
</Attributes>
5656
<Docs>
57-
<summary>Represent a type can be used to index a collection either from the start or the end.</summary>
57+
<summary>Represents a type that can be used to index a collection either from the beginning or the end.</summary>
5858
<remarks>
59-
Index is used by the C# compiler to support the new index syntax
60-
<code>
61-
int[] someArray = new int[5] { 1, 2, 3, 4, 5 } ;
62-
int lastElement = someArray[^1]; // lastElement = 5
63-
</code></remarks>
59+
<format type="text/markdown"><![CDATA[
60+
61+
## Remarks
62+
63+
`Index` is used by the C# compiler to support the `^` or ["index from end" operator](/dotnet/csharp/language-reference/operators/member-access-operators#index-from-end-operator-):
64+
65+
```csharp
66+
int[] someArray = new int[5] { 1, 2, 3, 4, 5 };
67+
int lastElement = someArray[^1]; // lastElement = 5
68+
```
69+
70+
]]></format>
71+
</remarks>
6472
</Docs>
6573
<Members>
6674
<Member MemberName=".ctor">
@@ -97,12 +105,19 @@
97105
<Parameter Name="fromEnd" Type="System.Boolean" />
98106
</Parameters>
99107
<Docs>
100-
<param name="value">The index value. it has to be zero or positive number.</param>
101-
<param name="fromEnd">Indicating if the index is from the start or from the end.</param>
102-
<summary>Construct an Index using a value and indicating if the index is from the start or from the end.</summary>
108+
<param name="value">The index value. It has to be greater then or equal to zero.</param>
109+
<param name="fromEnd">
110+
<see langword="true" /> to index from the end of the collection, or <see langword="false" /> to index from the beginning of the collection.</param>
111+
<summary>Initializes a new <see cref="T:System.Index" /> with a specified index position and a value that indicates if the index is from the beginning or the end of a collection.</summary>
103112
<remarks>
104-
If the Index constructed from the end, index value 1 means pointing at the last element and index value 0 means pointing at beyond last element.
105-
</remarks>
113+
<format type="text/markdown"><![CDATA[
114+
115+
## Remarks
116+
117+
If the <xref:System.Index> is constructed from the end, an index value of 1 points to the last element, and an index value of 0 points beyond the last element.
118+
119+
]]></format>
120+
</remarks>
106121
</Docs>
107122
</Member>
108123
<Member MemberName="End">
@@ -139,7 +154,7 @@
139154
<ReturnType>System.Index</ReturnType>
140155
</ReturnValue>
141156
<Docs>
142-
<summary>Create an Index pointing at beyond last element.</summary>
157+
<summary>Gets an <see cref="T:System.Index" /> that points beyond the last element.</summary>
143158
<value>An index that points beyond the last element.</value>
144159
<remarks>To be added.</remarks>
145160
</Docs>
@@ -184,8 +199,8 @@
184199
<Parameter Name="other" Type="System.Index" />
185200
</Parameters>
186201
<Docs>
187-
<param name="other">An object to compare with this object</param>
188-
<summary>Indicates whether the current Index object is equal to another Index object.</summary>
202+
<param name="other">The object to compare with this instance.</param>
203+
<summary>Returns a value that indicates whether the current object is equal to another <see cref="T:System.Index" /> object.</summary>
189204
<returns>
190205
<see langword="true" /> if the current Index object is equal to <paramref name="other" />; <see langword="false" /> otherwise.</returns>
191206
<remarks>To be added.</remarks>
@@ -236,8 +251,8 @@
236251
</Parameter>
237252
</Parameters>
238253
<Docs>
239-
<param name="value">An object to compare with this object</param>
240-
<summary>Indicates whether the current Index object is equal to another object of the same type.</summary>
254+
<param name="value">An object to compare with this instance.</param>
255+
<summary>Indicates whether the current Index object is equal to a specified object.</summary>
241256
<returns>
242257
<see langword="true" /> if <paramref name="value" /> is of type <see cref="T:System.Index" /> and is equal to the current instance; <see langword="false" /> otherwise.</returns>
243258
<remarks>To be added.</remarks>
@@ -280,8 +295,8 @@
280295
<Parameter Name="value" Type="System.Int32" />
281296
</Parameters>
282297
<Docs>
283-
<param name="value">The index value from the end.</param>
284-
<summary>Create an Index from the end at the position indicated by the value.</summary>
298+
<param name="value">The index value from the end of a collection.</param>
299+
<summary>Creates an <see cref="T:System.Index" /> from the end of a collection at a specified index position.</summary>
285300
<returns>The index value.</returns>
286301
<remarks>To be added.</remarks>
287302
</Docs>
@@ -323,8 +338,8 @@
323338
<Parameter Name="value" Type="System.Int32" />
324339
</Parameters>
325340
<Docs>
326-
<param name="value">The index value from the start.</param>
327-
<summary>Create an Index from the start at the position indicated by the value.</summary>
341+
<param name="value">The index position from the start of a collection.</param>
342+
<summary>Creates an <see cref="T:System.Index" /> from the specified index at the start of a collection.</summary>
328343
<returns>The index value.</returns>
329344
<remarks>To be added.</remarks>
330345
</Docs>
@@ -406,15 +421,20 @@
406421
<Parameter Name="length" Type="System.Int32" />
407422
</Parameters>
408423
<Docs>
409-
<param name="length">The length of the collection that the Index will be used with. length has to be a positive value</param>
410-
<summary>Calculate the offset from the start using the giving collection length.</summary>
424+
<param name="length">The length of the collection that the Index will be used with. Must be a positive value.</param>
425+
<summary>Calculates the offset from the start of the collection using the specified collection length.</summary>
411426
<returns>The offset.</returns>
412427
<remarks>
413-
For performance reason, we don't validate the input length parameter and the returned offset value against negative values.
414-
we don't validate either the returned offset is greater than the input length.
415-
It is expected Index will be used with collections which always have non negative length/count. If the returned offset is negative and
416-
then used to index a collection will get out of range exception which will be same affect as the validation.
417-
</remarks>
428+
<format type="text/markdown"><![CDATA[
429+
430+
## Remarks
431+
432+
For performance reasons, this method does not validate if `length` or the returned value are negative. It also doesn't validate if the returned value is greater than `length`.
433+
434+
Collections are not expected to have a negative length/count. If this method's returned offset is negative and is then used to index a collection, the runtime will throw <xref:System.ArgumentOutOfRangeException>, which will have the same effect as validation.
435+
436+
]]></format>
437+
</remarks>
418438
</Docs>
419439
</Member>
420440
<Member MemberName="IsFromEnd">
@@ -451,7 +471,7 @@
451471
<ReturnType>System.Boolean</ReturnType>
452472
</ReturnValue>
453473
<Docs>
454-
<summary>Indicates whether the index is from the start or the end.</summary>
474+
<summary>Gets a value that indicates whether the index is from the start or the end.</summary>
455475
<value>
456476
<see langword="true" /> if the Index is from the end; otherwise, <see langword="false" />.</value>
457477
<remarks>To be added.</remarks>
@@ -495,7 +515,7 @@
495515
</Parameters>
496516
<Docs>
497517
<param name="value">The integer to convert.</param>
498-
<summary>Converts integer number to an Index.</summary>
518+
<summary>Converts an integer number to an <see cref="T:System.Index" />.</summary>
499519
<returns>An index representing the integer.</returns>
500520
<remarks>To be added.</remarks>
501521
</Docs>
@@ -534,7 +554,7 @@
534554
<ReturnType>System.Index</ReturnType>
535555
</ReturnValue>
536556
<Docs>
537-
<summary>Create an Index pointing at first element.</summary>
557+
<summary>Gets an <see cref="T:System.Index" /> that points to the first element of a collection.</summary>
538558
<value>An instance that points to the first element of a collection.</value>
539559
<remarks>To be added.</remarks>
540560
</Docs>
@@ -574,7 +594,7 @@
574594
</ReturnValue>
575595
<Parameters />
576596
<Docs>
577-
<summary>Converts the value of the current Index object to its equivalent string representation.</summary>
597+
<summary>Returns the string representation of the current <see cref="T:System.Index" /> instance.</summary>
578598
<returns>The string representation of the <see cref="T:System.Index" />.</returns>
579599
<remarks>To be added.</remarks>
580600
</Docs>
@@ -613,7 +633,7 @@
613633
<ReturnType>System.Int32</ReturnType>
614634
</ReturnValue>
615635
<Docs>
616-
<summary>Returns the index value.</summary>
636+
<summary>Gets the index value.</summary>
617637
<value>The index value.</value>
618638
<remarks>To be added.</remarks>
619639
</Docs>

‎xml/System/Range.xml

Lines changed: 38 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -54,14 +54,22 @@
5454
</Attribute>
5555
</Attributes>
5656
<Docs>
57-
<summary>Represent a range has start and end indexes.</summary>
57+
<summary>Represents a range that has start and end indexes.</summary>
5858
<remarks>
59-
Range is used by the C# compiler to support the range syntax.
60-
<code>
61-
int[] someArray = new int[5] { 1, 2, 3, 4, 5 };
62-
int[] subArray1 = someArray[0..2]; // { 1, 2 }
63-
int[] subArray2 = someArray[1..^0]; // { 2, 3, 4, 5 }
64-
</code></remarks>
59+
<format type="text/markdown"><![CDATA[
60+
61+
## Remarks
62+
63+
`Range` is used by the C# compiler to support the range syntax:
64+
65+
```csharp
66+
int[] someArray = new int[5] { 1, 2, 3, 4, 5 };
67+
int[] subArray1 = someArray[0..2]; // { 1, 2 }
68+
int[] subArray2 = someArray[1..^0]; // { 2, 3, 4, 5 }
69+
```
70+
71+
]]></format>
72+
</remarks>
6573
</Docs>
6674
<Members>
6775
<Member MemberName=".ctor">
@@ -99,9 +107,9 @@
99107
<Parameter Name="end" Type="System.Index" />
100108
</Parameters>
101109
<Docs>
102-
<param name="start">Represent the inclusive start index of the range.</param>
103-
<param name="end">Represent the exclusive end index of the range.</param>
104-
<summary>Construct a Range object using the start and end indexes.</summary>
110+
<param name="start">The inclusive start index of the range.</param>
111+
<param name="end">The exclusive end index of the range.</param>
112+
<summary>Instantiates a new <see cref="T:System.Range" /> instance with the specified starting and ending indexes.</summary>
105113
<remarks>To be added.</remarks>
106114
</Docs>
107115
</Member>
@@ -139,7 +147,7 @@
139147
<ReturnType>System.Range</ReturnType>
140148
</ReturnValue>
141149
<Docs>
142-
<summary>Create a Range object starting from first element to the end.</summary>
150+
<summary>Gets a <see cref="T:System.Range" /> object that starts from the first element to the end.</summary>
143151
<value>A range from the start to the end.</value>
144152
<remarks>To be added.</remarks>
145153
</Docs>
@@ -178,7 +186,7 @@
178186
<ReturnType>System.Index</ReturnType>
179187
</ReturnValue>
180188
<Docs>
181-
<summary>Represent the exclusive end index of the Range.</summary>
189+
<summary>Gets an <see cref="T:System.Index" /> that represents the exclusive end index of the range.</summary>
182190
<value>The end index of the range.</value>
183191
<remarks>To be added.</remarks>
184192
</Docs>
@@ -221,7 +229,7 @@
221229
</Parameters>
222230
<Docs>
223231
<param name="end">The position of the last element up to which the <see cref="T:System.Range" /> object will be created.</param>
224-
<summary>Create a Range object starting from first element in the collection to the end Index.</summary>
232+
<summary>Creates a <see cref="T:System.Range" /> object starting from the first element in the collection to a specified end index.</summary>
225233
<returns>A range that starts from the first element to <paramref name="end" />.</returns>
226234
<remarks>To be added.</remarks>
227235
</Docs>
@@ -271,8 +279,8 @@
271279
</Parameter>
272280
</Parameters>
273281
<Docs>
274-
<param name="value">An object to compare with this object</param>
275-
<summary>Indicates whether the current Range object is equal to another object of the same type.</summary>
282+
<param name="value">An object to compare with this Range object.</param>
283+
<summary>Returns a value that indicates whether the current instance is equal to a specified object.</summary>
276284
<returns>
277285
<see langword="true" /> if <paramref name="value" /> is of type <see cref="T:System.Range" /> and is equal to the current instance; otherwise, <see langword="false" />.</returns>
278286
<remarks>To be added.</remarks>
@@ -318,8 +326,8 @@
318326
<Parameter Name="other" Type="System.Range" />
319327
</Parameters>
320328
<Docs>
321-
<param name="other">An object to compare with this object</param>
322-
<summary>Indicates whether the current Range object is equal to another Range object.</summary>
329+
<param name="other">A Range object to compare with this Range object.</param>
330+
<summary>Returns a value that indicates whether the current instance is equal to another <see cref="T:System.Range" /> object.</summary>
323331
<returns>
324332
<see langword="true" /> if the current instance is equal to <paramref name="other" />; otherwise, <see langword="false" />.</returns>
325333
<remarks>To be added.</remarks>
@@ -408,14 +416,18 @@
408416
<Parameter Name="length" Type="System.Int32" />
409417
</Parameters>
410418
<Docs>
411-
<param name="length">The length of the collection that the range will be used with. length has to be a positive value.</param>
412-
<summary>Calculate the start offset and length of range object using a collection length.</summary>
419+
<param name="length">A positive integer that represents the length of the collection that the range will be used with.</param>
420+
<summary>Calculates the start offset and length of the range object using a collection length.</summary>
413421
<returns>The start offset and length of the range.</returns>
414422
<remarks>
415-
For performance reason, we don't validate the input length parameter against negative values.
416-
It is expected Range will be used with collections which always have non negative length/count.
417-
We validate the range is inside the length scope though.
418-
</remarks>
423+
<format type="text/markdown"><![CDATA[
424+
425+
## Remarks
426+
427+
For performance reasons, this method doesn't validate `length` to ensure that it is not negative. It does ensure that `length` is within the current `Range` instance.
428+
429+
]]></format>
430+
</remarks>
419431
<exception cref="T:System.ArgumentOutOfRangeException">
420432
<paramref name="length" /> is outside the bounds of the current range.</exception>
421433
</Docs>
@@ -454,7 +466,7 @@
454466
<ReturnType>System.Index</ReturnType>
455467
</ReturnValue>
456468
<Docs>
457-
<summary>Represent the inclusive start index of the Range.</summary>
469+
<summary>Gets the inclusive start index of the <see cref="T:System.Range" />.</summary>
458470
<value>The inclusive start index of the range.</value>
459471
<remarks>To be added.</remarks>
460472
</Docs>
@@ -497,7 +509,7 @@
497509
</Parameters>
498510
<Docs>
499511
<param name="start">The position of the first element from which the Range will be created.</param>
500-
<summary>Create a Range object starting from start index to the end of the collection.</summary>
512+
<summary>Returns a new <see cref="T:System.Range" /> instance starting from a specified start index to the end of the collection.</summary>
501513
<returns>A range from <paramref name="start" /> to the end of the collection.</returns>
502514
<remarks>To be added.</remarks>
503515
</Docs>
@@ -537,7 +549,7 @@
537549
</ReturnValue>
538550
<Parameters />
539551
<Docs>
540-
<summary>Converts the value of the current Range object to its equivalent string representation.</summary>
552+
<summary>Returns the string representation of the current <see cref="T:System.Range" /> object.</summary>
541553
<returns>The string representation of the range.</returns>
542554
<remarks>To be added.</remarks>
543555
</Docs>

0 commit comments

Comments
 (0)