Skip to content

Commit 8c61081

Browse files
carlossanlopRon Petrusha
carlossanlop
authored and
Ron Petrusha
committed
Automatic port of System.Buffers triple slash comments (#2666)
* Automatic port of System.Buffers triple slash comments * rpetrusha suggestions minus 3 Co-Authored-By: Ron Petrusha <[email protected]> * Update ArrayBufferWriter`1.xml * Update ArrayBufferWriter`1.xml * Update SequenceReader`1.xml * corrected bad paramref * Corrected bad langword tag. * Fixed bad langword tag. * Suggestions by mairaw Co-Authored-By: Maira Wenzel <[email protected]> Co-Authored-By: Ron Petrusha <[email protected]> * Fixed broken link.
1 parent 5484b11 commit 8c61081

File tree

5 files changed

+186
-142
lines changed

5 files changed

+186
-142
lines changed

‎xml/System.Buffers/ArrayBufferWriter`1.xml

Lines changed: 60 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@
2121
</Interface>
2222
</Interfaces>
2323
<Docs>
24-
<typeparam name="T">To be added.</typeparam>
25-
<summary>To be added.</summary>
24+
<typeparam name="T">The type of the items in this <see cref="T:System.Buffers.ArrayBufferWriter`1" /> instance.</typeparam>
25+
<summary>Represents a heap-based, array-backed output sink into which <typeparam name="T" /> data can be written.</summary>
2626
<remarks>To be added.</remarks>
2727
</Docs>
2828
<Members>
@@ -39,7 +39,7 @@
3939
</AssemblyInfo>
4040
<Parameters />
4141
<Docs>
42-
<summary>To be added.</summary>
42+
<summary>Creates an instance of an <see cref="T:System.Buffers.ArrayBufferWriter`1" /> to which data can be written, with the default initial capacity.</summary>
4343
<remarks>To be added.</remarks>
4444
</Docs>
4545
</Member>
@@ -59,9 +59,12 @@
5959
<Parameter Name="initialCapacity" Type="System.Int32" />
6060
</Parameters>
6161
<Docs>
62-
<param name="initialCapacity">To be added.</param>
63-
<summary>To be added.</summary>
62+
<param name="initialCapacity">The minimum capacity with which to initialize the underlying buffer.</param>
63+
<summary>Creates an instance of an <see cref="T:System.Buffers.ArrayBufferWriter`1" /> to which data can be written, with a specified initial capacity.</summary>
6464
<remarks>To be added.</remarks>
65+
<exception cref="T:System.ArgumentException">
66+
<paramref name="initialCapacity" /> is less than or equal to 0.
67+
</exception>
6568
</Docs>
6669
</Member>
6770
<Member MemberName="Advance">
@@ -86,9 +89,20 @@
8689
<Parameter Name="count" Type="System.Int32" />
8790
</Parameters>
8891
<Docs>
89-
<param name="count">To be added.</param>
90-
<summary>To be added.</summary>
91-
<remarks>To be added.</remarks>
92+
<param name="count">The number of items written.</param>
93+
<summary>Notifies the <see cref="T:System.Buffers.IBufferWriter`1" /> that <paramref name="count" /> items were written to the output <see cref="T:System.Span`1" />/<see cref="T:System.Memory`1" /></summary>
94+
<remarks>
95+
<format type="text/markdown"><![CDATA[
96+
You must request a new buffer after calling `Advance` to continue writing more data and cannot write to a previously acquired buffer.
97+
98+
]]></format>
99+
</remarks>
100+
<exception cref="T:System.ArgumentException">
101+
<paramref name="count" /> is negative.
102+
</exception>
103+
<exception cref="T:System.InvalidOperationException">
104+
The method call attempts to advance past the end of the underlying buffer.
105+
</exception>
92106
</Docs>
93107
</Member>
94108
<Member MemberName="Capacity">
@@ -107,8 +121,8 @@
107121
<ReturnType>System.Int32</ReturnType>
108122
</ReturnValue>
109123
<Docs>
110-
<summary>To be added.</summary>
111-
<value>To be added.</value>
124+
<summary>Gets the total amount of space within the underlying buffer.</summary>
125+
<value>The total capacity of the underlying buffer.</value>
112126
<remarks>To be added.</remarks>
113127
</Docs>
114128
</Member>
@@ -129,8 +143,12 @@
129143
</ReturnValue>
130144
<Parameters />
131145
<Docs>
132-
<summary>To be added.</summary>
133-
<remarks>To be added.</remarks>
146+
<summary>Clears the data written to the underlying buffer.</summary>
147+
<remarks>
148+
<format type="text/markdown"><![CDATA[
149+
You must clear the <xref:System.Buffers.ArrayBufferWriter`1> before trying to reuse it.
150+
]]></format>
151+
</remarks>
134152
</Docs>
135153
</Member>
136154
<Member MemberName="FreeCapacity">
@@ -149,8 +167,8 @@
149167
<ReturnType>System.Int32</ReturnType>
150168
</ReturnValue>
151169
<Docs>
152-
<summary>To be added.</summary>
153-
<value>To be added.</value>
170+
<summary>Gets the amount of available space that can be written to without forcing the underlying buffer to grow.</summary>
171+
<value>The space available for writing without forcing the underlying buffer to grow.</value>
154172
<remarks>To be added.</remarks>
155173
</Docs>
156174
</Member>
@@ -175,10 +193,17 @@
175193
<Parameter Name="sizeHint" Type="System.Int32" />
176194
</Parameters>
177195
<Docs>
178-
<param name="sizeHint">To be added.</param>
179-
<summary>To be added.</summary>
180-
<returns>To be added.</returns>
181-
<remarks>To be added.</remarks>
196+
<param name="sizeHint">The minimum requested length of the <see cref="T:System.Memory`1" />.</param>
197+
<summary>Returns a <see cref="T:System.Memory`1" /> to write to that is at least the length specified by <paramref name="sizeHint" />.</summary>
198+
<returns>A <see cref="T:System.Memory`1" /> whose length is at least <paramref name="sizeHint" />. If <paramref name="sizeHint" /> is not provided or is equal to 0, some non-empty buffer is returned.</returns>
199+
<remarks>
200+
<format type="text/markdown"><![CDATA[
201+
This method never returns <xref:System.Memory%601.Empty?displayProperty=nameWithType>.
202+
]]></format>
203+
</remarks>
204+
<exception cref="T:System.ArgumentException">
205+
<paramref name="sizeHint" /> is negative.
206+
</exception>
182207
</Docs>
183208
</Member>
184209
<Member MemberName="GetSpan">
@@ -203,9 +228,17 @@
203228
</Parameters>
204229
<Docs>
205230
<param name="sizeHint">To be added.</param>
206-
<summary>To be added.</summary>
207-
<returns>To be added.</returns>
208-
<remarks>To be added.</remarks>
231+
<summary>Returns a <see cref="T:System.Span`1" /> to write to that is at least a specified length.
232+
</summary>
233+
<returns>A span of at least <paramref name="sizeHint" /> in length. If <paramref name="sizeHint" /> is not provided or is equal to 0, some non-empty buffer is returned.</returns>
234+
<remarks>
235+
<format type="text/markdown"><![CDATA[
236+
This method never returns <xref:System.Memory%601.Empty?displayProperty=nameWithType>.
237+
]]></format>
238+
</remarks>
239+
<exception cref="T:System.ArgumentException">
240+
<paramref name="sizeHint" /> is negative.
241+
</exception>
209242
</Docs>
210243
</Member>
211244
<Member MemberName="WrittenCount">
@@ -224,8 +257,8 @@
224257
<ReturnType>System.Int32</ReturnType>
225258
</ReturnValue>
226259
<Docs>
227-
<summary>To be added.</summary>
228-
<value>To be added.</value>
260+
<summary>Gets the amount of data written to the underlying buffer.</summary>
261+
<value>The amount of data written to the underlying buffer.</value>
229262
<remarks>To be added.</remarks>
230263
</Docs>
231264
</Member>
@@ -245,8 +278,8 @@
245278
<ReturnType>System.ReadOnlyMemory&lt;T&gt;</ReturnType>
246279
</ReturnValue>
247280
<Docs>
248-
<summary>To be added.</summary>
249-
<value>To be added.</value>
281+
<summary>Gets a <see cref="T:System.ReadOnlyMemory`1" /> that contains the data written to the underlying buffer so far.</summary>
282+
<value>The data written to the underlying buffer.</value>
250283
<remarks>To be added.</remarks>
251284
</Docs>
252285
</Member>
@@ -266,10 +299,10 @@
266299
<ReturnType>System.ReadOnlySpan&lt;T&gt;</ReturnType>
267300
</ReturnValue>
268301
<Docs>
269-
<summary>To be added.</summary>
302+
<summary>Gets a <see cref="T:System.ReadOnlySpan`1" /> that contains the data written to the underlying buffer so far.</summary>
270303
<value>To be added.</value>
271304
<remarks>To be added.</remarks>
272305
</Docs>
273306
</Member>
274307
</Members>
275-
</Type>
308+
</Type>

‎xml/System.Buffers/BuffersExtensions.xml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,10 @@
173173
<param name="value">The read-only span to be written to <paramref name="writer" />.</param>
174174
<summary>Writes the contents of <paramref name="value" /> to <paramref name="writer" />.</summary>
175175
<remarks>To be added.</remarks>
176+
<exception cref="T:System.ArgumentOutOfRangeException">
177+
<paramref name="writer" /> is shorter than <paramref name="value" />.
178+
</exception>
176179
</Docs>
177180
</Member>
178181
</Members>
179-
</Type>
182+
</Type>

‎xml/System.Buffers/ReadOnlySequence`1.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -255,7 +255,7 @@ The consumer is expected to manage the lifetime of memory until <see cref="T:Sys
255255
<ReturnType>System.ReadOnlySpan&lt;T&gt;</ReturnType>
256256
</ReturnValue>
257257
<Docs>
258-
<summary>To be added.</summary>
258+
<summary>Gets the <see cref="T:System.ReadOnlySpan`1" /> from the first segment.</summary>
259259
<value>To be added.</value>
260260
<remarks>To be added.</remarks>
261261
</Docs>
@@ -819,4 +819,4 @@ The consumer is expected to manage the lifetime of memory until <see cref="T:Sys
819819
</Docs>
820820
</Member>
821821
</Members>
822-
</Type>
822+
</Type>

‎xml/System.Buffers/SequenceReaderExtensions.xml

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@
4040
<Docs>
4141
<param name="reader">To be added.</param>
4242
<param name="value">To be added.</param>
43-
<summary>To be added.</summary>
44-
<returns>To be added.</returns>
43+
<summary>Reads a big-endian <see cref="T:System.Int16" />.</summary>
44+
<returns><see langword="true" /> if the read operation is successful; <see langword="false" /> if there isn't enough data for an <see cref="T:System.Int16" />.</returns>
4545
<remarks>To be added.</remarks>
4646
</Docs>
4747
</Member>
@@ -67,8 +67,8 @@
6767
<Docs>
6868
<param name="reader">To be added.</param>
6969
<param name="value">To be added.</param>
70-
<summary>To be added.</summary>
71-
<returns>To be added.</returns>
70+
<summary>Reads a big-endian <see cref="T:System.Int32" />.</summary>
71+
<returns><see langword="true" /> if the read operation is successful; <see langword="false" /> if there isn't enough data for an <see cref="T:System.Int32" />.</returns>
7272
<remarks>To be added.</remarks>
7373
</Docs>
7474
</Member>
@@ -94,10 +94,10 @@
9494
<Docs>
9595
<param name="reader">To be added.</param>
9696
<param name="value">To be added.</param>
97-
<summary>To be added.</summary>
98-
<returns>To be added.</returns>
97+
<summary>Reads a little-endian <see cref="T:System.Int16" />.</summary>
98+
<returns><see langword="true" /> if the read operation is successful; <see langword="false" /> if there isn't enough data for an <see cref="T:System.Int16" />.</returns>
9999
<remarks>To be added.</remarks>
100100
</Docs>
101101
</Member>
102102
</Members>
103-
</Type>
103+
</Type>

0 commit comments

Comments
 (0)