Skip to content

Commit a03587c

Browse files
carlossanlopRon Petrusha
carlossanlop
and
Ron Petrusha
committed
Port System.IO* source comments to Docs (#2495)
* Port System.IO* source comments to Docs * Apply suggestions from code review Suggestions by rpetrusha Co-Authored-By: Ron Petrusha <[email protected]>
1 parent cb46620 commit a03587c

File tree

6 files changed

+50
-34
lines changed

6 files changed

+50
-34
lines changed

‎xml/System.IO.Packaging/PackUriHelper.xml

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -839,10 +839,16 @@
839839
</Parameters>
840840
<Docs>
841841
<param name="partUri">The [!INCLUDE[TLA2#tla_uri](~/includes/tla2sharptla-uri-md.md)] to check for a <see cref="T:System.IO.Packaging.PackageRelationship" /> part.</param>
842-
<summary>Returns a value that indicates whether a specified [!INCLUDE[TLA2#tla_uri](~/includes/tla2sharptla-uri-md.md)] is the [!INCLUDE[TLA2#tla_uri](~/includes/tla2sharptla-uri-md.md)] of a <see cref="T:System.IO.Packaging.PackageRelationship" /> part.</summary>
842+
<summary>Returns a value that indicates whether a specified URI is the URI of a <see cref="T:System.IO.Packaging.PackageRelationship" /> part.</summary>
843843
<returns>
844844
<see langword="true" /> if <paramref name="partUri" /> identifies a <see cref="T:System.IO.Packaging.PackageRelationship" /> part; otherwise, <see langword="false" />.</returns>
845-
<remarks>To be added.</remarks>
845+
<remarks>
846+
<format type="text/markdown"><![CDATA[
847+
848+
This method does not inspect the part contents; it is based solely on the name.
849+
850+
]]></format>
851+
</remarks>
846852
<exception cref="T:System.ArgumentNullException">
847853
<paramref name="partUri" /> is <see langword="null" />.</exception>
848854
<exception cref="T:System.ArgumentException">
@@ -955,4 +961,4 @@
955961
</Docs>
956962
</Member>
957963
</Members>
958-
</Type>
964+
</Type>

‎xml/System.IO.Packaging/ZipPackage.xml

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -250,8 +250,18 @@
250250
<Docs>
251251
<summary>This method is for a custom implementation specific to the file format. This method retrieves the actual parts from the underlying <see cref="T:System.IO.Packaging.ZipPackage" />.</summary>
252252
<returns>An array of <see cref="T:System.IO.Packaging.ZipPackagePart" /> objects.</returns>
253-
<remarks>To be added.</remarks>
253+
<remarks>
254+
<format type="text/markdown"><![CDATA[
255+
256+
Some or all of the parts may be interleaved. The Part object for an interleaved part encapsulates the Uri of the proper part name and the ZipFileInfo of the initial piece. This function does not go through the extra work of checking piece naming validity throughout the package.
257+
258+
This means that interleaved parts without an initial piece will be silently ignored. Other naming anomalies are caught at the stream level when an I/O operation involves an anomalous or missing piece.
259+
260+
This function reads directly from the underlying IO layer and is supposed to be called just once in the lifetime of a package (at initialization time).
261+
262+
]]></format>
263+
</remarks>
254264
</Docs>
255265
</Member>
256266
</Members>
257-
</Type>
267+
</Type>

‎xml/System.IO.Pipelines/PipeReader.xml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -208,10 +208,10 @@
208208
<Parameter Name="readerOptions" Type="System.IO.Pipelines.StreamPipeReaderOptions" Index="1" FrameworkAlternate="dotnet-plat-ext-3.0" />
209209
</Parameters>
210210
<Docs>
211-
<param name="stream">To be added.</param>
212-
<param name="readerOptions">To be added.</param>
213-
<summary>To be added.</summary>
214-
<returns>To be added.</returns>
211+
<param name="stream">The stream that the pipe reader will wrap.</param>
212+
<param name="readerOptions">The options to configure the pipe reader.</param>
213+
<summary>Creates a <see cref="T:System.IO.Pipelines.PipeReader" /> wrapping the specified <see cref="T:System.IO.Stream" />.</summary>
214+
<returns>A <see cref="T:System.IO.Pipelines.PipeReader" /> that wraps the <see cref="T:System.IO.Stream" />.</returns>
215215
<remarks>To be added.</remarks>
216216
</Docs>
217217
</Member>

‎xml/System.IO.Pipelines/PipeWriter.xml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -185,10 +185,10 @@
185185
<Parameter Name="writerOptions" Type="System.IO.Pipelines.StreamPipeWriterOptions" Index="1" FrameworkAlternate="dotnet-plat-ext-3.0" />
186186
</Parameters>
187187
<Docs>
188-
<param name="stream">To be added.</param>
189-
<param name="writerOptions">To be added.</param>
190-
<summary>To be added.</summary>
191-
<returns>To be added.</returns>
188+
<param name="stream">The stream that the pipe writer will wrap.</param>
189+
<param name="writerOptions">The options to configure the pipe writer.</param>
190+
<summary>Creates a <see cref="T:System.IO.Pipelines.PipeWriter" /> wrapping the specified <see cref="T:System.IO.Stream" />.</summary>
191+
<returns>A <see cref="T:System.IO.Pipelines.PipeWriter" /> that wraps the <see cref="T:System.IO.Stream" />.</returns>
192192
<remarks>To be added.</remarks>
193193
</Docs>
194194
</Member>

‎xml/System.IO.Pipelines/StreamPipeReaderOptions.xml

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
</Base>
1515
<Interfaces />
1616
<Docs>
17-
<summary>To be added.</summary>
17+
<summary>Represents a set of options for controlling the creation of the <see cref="T:System.IO.Pipelines.PipeReader" />.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -35,10 +35,10 @@
3535
<Parameter Name="minimumReadSize" Type="System.Int32" />
3636
</Parameters>
3737
<Docs>
38-
<param name="pool">To be added.</param>
39-
<param name="bufferSize">To be added.</param>
40-
<param name="minimumReadSize">To be added.</param>
41-
<summary>To be added.</summary>
38+
<param name="pool">The memory pool from which memory will be rented.</param>
39+
<param name="bufferSize">The desired minimum buffer size that will be used to rent memory from the pool.</param>
40+
<param name="minimumReadSize">The desired minimum number of bytes that will remain in the buffer before a new buffer is allocated.</param>
41+
<summary>Creates a new instance of <see cref="T:System.IO.Pipelines.StreamPipeReaderOptions" />.</summary>
4242
<remarks>To be added.</remarks>
4343
</Docs>
4444
</Member>
@@ -58,8 +58,8 @@
5858
<ReturnType>System.Int32</ReturnType>
5959
</ReturnValue>
6060
<Docs>
61-
<summary>To be added.</summary>
62-
<value>To be added.</value>
61+
<summary>Gets the minimum buffer size to use when renting memory from the <see cref="P:System.IO.Pipelines.StreamPipeReaderOptions.Pool" />.</summary>
62+
<value>The buffer size.</value>
6363
<remarks>To be added.</remarks>
6464
</Docs>
6565
</Member>
@@ -79,8 +79,8 @@
7979
<ReturnType>System.Int32</ReturnType>
8080
</ReturnValue>
8181
<Docs>
82-
<summary>To be added.</summary>
83-
<value>To be added.</value>
82+
<summary>Gets the threshold of remaining bytes in the buffer before a new buffer is allocated.</summary>
83+
<value>The minimum read size.</value>
8484
<remarks>To be added.</remarks>
8585
</Docs>
8686
</Member>
@@ -100,10 +100,10 @@
100100
<ReturnType>System.Buffers.MemoryPool&lt;System.Byte&gt;</ReturnType>
101101
</ReturnValue>
102102
<Docs>
103-
<summary>To be added.</summary>
104-
<value>To be added.</value>
103+
<summary>Gets the <see cref="T:System.Buffers.MemoryPool`1" /> to use when allocating memory.</summary>
104+
<value>A memory pool instance.</value>
105105
<remarks>To be added.</remarks>
106106
</Docs>
107107
</Member>
108108
</Members>
109-
</Type>
109+
</Type>

‎xml/System.IO.Pipelines/StreamPipeWriterOptions.xml

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
</Base>
1515
<Interfaces />
1616
<Docs>
17-
<summary>To be added.</summary>
17+
<summary>Represents a set of options for controlling the creation of the <see cref="T:System.IO.Pipelines.PipeWriter" />.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -34,9 +34,9 @@
3434
<Parameter Name="minimumBufferSize" Type="System.Int32" />
3535
</Parameters>
3636
<Docs>
37-
<param name="pool">To be added.</param>
38-
<param name="minimumBufferSize">To be added.</param>
39-
<summary>To be added.</summary>
37+
<param name="pool">A memory pool from which memory will be rented.</param>
38+
<param name="minimumBufferSize">The desired minimum buffer size that will be used to rent memory from the pool.</param>
39+
<summary>Creates a new instance of <see cref="T:System.IO.Pipelines.StreamPipeWriterOptions" />.</summary>
4040
<remarks>To be added.</remarks>
4141
</Docs>
4242
</Member>
@@ -56,8 +56,8 @@
5656
<ReturnType>System.Int32</ReturnType>
5757
</ReturnValue>
5858
<Docs>
59-
<summary>To be added.</summary>
60-
<value>To be added.</value>
59+
<summary>Gets the minimum buffer size to use when renting memory from the <see cref="P:System.IO.Pipelines.StreamPipeWriterOptions.Pool" />.</summary>
60+
<value>An integer representing the minimum buffer size.</value>
6161
<remarks>To be added.</remarks>
6262
</Docs>
6363
</Member>
@@ -77,10 +77,10 @@
7777
<ReturnType>System.Buffers.MemoryPool&lt;System.Byte&gt;</ReturnType>
7878
</ReturnValue>
7979
<Docs>
80-
<summary>To be added.</summary>
81-
<value>To be added.</value>
80+
<summary>Gets the <see cref="T:System.Buffers.MemoryPool`1" /> to use when allocating memory.</summary>
81+
<value>A memory pool instance.</value>
8282
<remarks>To be added.</remarks>
8383
</Docs>
8484
</Member>
8585
</Members>
86-
</Type>
86+
</Type>

0 commit comments

Comments
 (0)