Skip to content

Automatic port of System.Buffers triple slash comments #2666

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Jul 12, 2019
Merged

Automatic port of System.Buffers triple slash comments #2666

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f5ffebd
Automatic port of System.Buffers triple slash comments
carlossanlop Jul 1, 2019
9bdbf38
rpetrusha suggestions minus 3
carlossanlop Jul 3, 2019
ef7b0bf
Update ArrayBufferWriter`1.xml
Jul 9, 2019
d148d56
Update ArrayBufferWriter`1.xml
Jul 9, 2019
f486ff9
Update SequenceReader`1.xml
Jul 9, 2019
2237be3
corrected bad paramref
Jul 9, 2019
fbac43c
Corrected bad langword tag.
Jul 9, 2019
fd1ae24
Fixed bad langword tag.
Jul 9, 2019
11130e8
Suggestions by mairaw
carlossanlop Jul 9, 2019
14132d1
Fixed broken link.
Jul 11, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 60 additions & 27 deletions xml/System.Buffers/ArrayBufferWriter`1.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@
</Interface>
</Interfaces>
<Docs>
<typeparam name="T">To be added.</typeparam>
<summary>To be added.</summary>
<typeparam name="T">The type of the items in this <see cref="T:System.Buffers.ArrayBufferWriter`1" /> instance.</typeparam>
<summary>Represents a heap-based, array-backed output sink into which <typeparam name="T" /> data can be written.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -39,7 +39,7 @@
</AssemblyInfo>
<Parameters />
<Docs>
<summary>To be added.</summary>
<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>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -59,9 +59,12 @@
<Parameter Name="initialCapacity" Type="System.Int32" />
</Parameters>
<Docs>
<param name="initialCapacity">To be added.</param>
<summary>To be added.</summary>
<param name="initialCapacity">The minimum capacity with which to initialize the underlying buffer.</param>
<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>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="initialCapacity" /> is less than or equal to 0.
</exception>
</Docs>
</Member>
<Member MemberName="Advance">
Expand All @@ -86,9 +89,20 @@
<Parameter Name="count" Type="System.Int32" />
</Parameters>
<Docs>
<param name="count">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="count">The number of items written.</param>
<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>
<remarks>
<format type="text/markdown"><![CDATA[
You must request a new buffer after calling `Advance` to continue writing more data and cannot write to a previously acquired buffer.

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="count" /> is negative.
</exception>
<exception cref="T:System.InvalidOperationException">
The method call attempts to advance past the end of the underlying buffer.
</exception>
</Docs>
</Member>
<Member MemberName="Capacity">
Expand All @@ -107,8 +121,8 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the total amount of space within the underlying buffer.</summary>
<value>The total capacity of the underlying buffer.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -129,8 +143,12 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<summary>Clears the data written to the underlying buffer.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
You must clear the <xref:System.Buffers.ArrayBufferWriter`1> before trying to reuse it.
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="FreeCapacity">
Expand All @@ -149,8 +167,8 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the amount of available space that can be written to without forcing the underlying buffer to grow.</summary>
<value>The space available for writing without forcing the underlying buffer to grow.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -175,10 +193,17 @@
<Parameter Name="sizeHint" Type="System.Int32" />
</Parameters>
<Docs>
<param name="sizeHint">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="sizeHint">The minimum requested length of the <see cref="T:System.Memory`1" />.</param>
<summary>Returns a <see cref="T:System.Memory`1" /> to write to that is at least the length specified by <paramref name="sizeHint" />.</summary>
<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>
<remarks>
<format type="text/markdown"><![CDATA[
This method never returns <xref:System.Memory%601.Empty?displayProperty=nameWithType>.
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="sizeHint" /> is negative.
</exception>
</Docs>
</Member>
<Member MemberName="GetSpan">
Expand All @@ -203,9 +228,17 @@
</Parameters>
<Docs>
<param name="sizeHint">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Returns a <see cref="T:System.Span`1" /> to write to that is at least a specified length.
</summary>
<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>
<remarks>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is an issue with how remarks were written in the source which means only one of them got ported.

We should add the rest:
https://github.com/dotnet/corefx/blob/97d5957fc71853961082e22873d926269b291b92/src/Common/src/System/Buffers/ArrayBufferWriter.cs#L142-L150

Same problem with GetMemory.

<format type="text/markdown"><![CDATA[
This method never returns <xref:System.Memory%601.Empty?displayProperty=nameWithType>.
]]></format>
</remarks>
<exception cref="T:System.ArgumentException">
<paramref name="sizeHint" /> is negative.
</exception>
</Docs>
</Member>
<Member MemberName="WrittenCount">
Expand All @@ -224,8 +257,8 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the amount of data written to the underlying buffer.</summary>
<value>The amount of data written to the underlying buffer.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -245,8 +278,8 @@
<ReturnType>System.ReadOnlyMemory&lt;T&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets a <see cref="T:System.ReadOnlyMemory`1" /> that contains the data written to the underlying buffer so far.</summary>
<value>The data written to the underlying buffer.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -266,10 +299,10 @@
<ReturnType>System.ReadOnlySpan&lt;T&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Gets a <see cref="T:System.ReadOnlySpan`1" /> that contains the data written to the underlying buffer so far.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
</Members>
</Type>
</Type>
5 changes: 4 additions & 1 deletion xml/System.Buffers/BuffersExtensions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,10 @@
<param name="value">The read-only span to be written to <paramref name="writer" />.</param>
<summary>Writes the contents of <paramref name="value" /> to <paramref name="writer" />.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="writer" /> is shorter than <paramref name="value" />.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit:

<paramref name="writer" /> doesn't have enough space left to write the <paramref name="value" /> into.

</exception>
</Docs>
</Member>
</Members>
</Type>
</Type>
4 changes: 2 additions & 2 deletions xml/System.Buffers/ReadOnlySequence`1.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -255,7 +255,7 @@ The consumer is expected to manage the lifetime of memory until <see cref="T:Sys
<ReturnType>System.ReadOnlySpan&lt;T&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Gets the <see cref="T:System.ReadOnlySpan`1" /> from the first segment.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand Down Expand Up @@ -819,4 +819,4 @@ The consumer is expected to manage the lifetime of memory until <see cref="T:Sys
</Docs>
</Member>
</Members>
</Type>
</Type>
14 changes: 7 additions & 7 deletions xml/System.Buffers/SequenceReaderExtensions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@
<Docs>
<param name="reader">To be added.</param>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Reads a big-endian <see cref="T:System.Int16" />.</summary>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's something wrong with this file. It doesn't contain all 6 of the relevant APIs, but rather just 3:
https://github.com/dotnet/corefx/blob/97d5957fc71853961082e22873d926269b291b92/src/System.Memory/ref/System.Memory.cs#L396-L404

Is something broken in how the reflection tool is generating this?

Also note, there is Int16, Int64 mismatch happening in the API signature vs the description:
https://docs.microsoft.com/en-us/dotnet/api/system.buffers.sequencereaderextensions?view=netcore-3.0
image

It is correctly documented in source:
https://github.com/dotnet/corefx/blob/97d5957fc71853961082e22873d926269b291b92/src/System.Memory/src/System/Buffers/SequenceReaderExtensions.Binary.cs#L136-L154

<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>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -67,8 +67,8 @@
<Docs>
<param name="reader">To be added.</param>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Reads a big-endian <see cref="T:System.Int32" />.</summary>
<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>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -94,10 +94,10 @@
<Docs>
<param name="reader">To be added.</param>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Reads a little-endian <see cref="T:System.Int16" />.</summary>
<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>
<remarks>To be added.</remarks>
</Docs>
</Member>
</Members>
</Type>
</Type>
Loading