Skip to content

Commit 276601e

Browse files
BillWagnerBillWagner
authored
Merge pull request #3947 from dotnet/master
Merge master into live for publishing
2 parents 06619f5 + 0d8c72c commit 276601e

File tree

7 files changed

+304
-89
lines changed

7 files changed

+304
-89
lines changed

‎xml/System.IO.Pipes/PipesAclExtensions.xml

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
</Base>
1818
<Interfaces />
1919
<Docs>
20-
<summary>To be added.</summary>
20+
<summary>Provides Windows-specific static extension methods for manipulating Access Control List (ACL) security attributes for pipe streams.</summary>
2121
<remarks>To be added.</remarks>
2222
</Docs>
2323
<Members>
@@ -48,9 +48,9 @@
4848
<Parameter Name="stream" Type="System.IO.Pipes.PipeStream" RefType="this" />
4949
</Parameters>
5050
<Docs>
51-
<param name="stream">To be added.</param>
52-
<summary>To be added.</summary>
53-
<returns>To be added.</returns>
51+
<param name="stream">The existing pipe stream from which to obtain the security information.</param>
52+
<summary>Returns the security information of a pipe stream.</summary>
53+
<returns>The security descriptors of all the access control sections of the pipe stream.</returns>
5454
<remarks>To be added.</remarks>
5555
</Docs>
5656
</Member>
@@ -81,10 +81,16 @@
8181
<Parameter Name="pipeSecurity" Type="System.IO.Pipes.PipeSecurity" />
8282
</Parameters>
8383
<Docs>
84-
<param name="stream">To be added.</param>
85-
<param name="pipeSecurity">To be added.</param>
86-
<summary>To be added.</summary>
84+
<param name="stream">An existing pipe stream.</param>
85+
<param name="pipeSecurity">The security information to apply to the pipe stream.</param>
86+
<summary>Changes the security attributes of an existing pipe stream.</summary>
8787
<remarks>To be added.</remarks>
88+
<exception cref="ArgumentNullException">
89+
<paramref name="pipeSecurity" /> is <see langword="null" />.
90+
</exception>
91+
<exception cref="IOException">
92+
<paramref name="stream" /> is a disconnected <see cref="T:System.IO.Pipes.NamedPipeClientStream" /> instance.
93+
</exception>
8894
</Docs>
8995
</Member>
9096
</Members>

‎xml/System.Runtime.InteropServices/Marshal.xml

Lines changed: 51 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6585,10 +6585,18 @@ There is a difference in the behavior of the `GetLastWin32Error` method on .NET
65856585
<Parameter Name="ptr" Type="System.IntPtr" Index="0" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1" />
65866586
</Parameters>
65876587
<Docs>
6588-
<param name="ptr">To be added.</param>
6589-
<summary>To be added.</summary>
6590-
<returns>To be added.</returns>
6591-
<remarks>To be added.</remarks>
6588+
<param name="ptr">The address of the first character of the unmanaged string.</param>
6589+
<summary>Allocates a managed <see cref="T:System.String" /> and copies all characters up to the first null character from an unmanaged UTF-8 string into it.</summary>
6590+
<returns>A managed string that holds a copy of the unmanaged string if the value of the <paramref name="ptr" /> parameter is not <see langword="null" />; otherwise, this method returns <see langword="null" />.</returns>
6591+
<remarks>
6592+
<format type="text/markdown"><![CDATA[
6593+
6594+
## Remarks
6595+
<xref:System.Runtime.InteropServices.Marshal.PtrToStringUTF8%2A> is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the <xref:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8%2A?displayProperty=nameWithType> methods.
6596+
]]></format>
6597+
6598+
</remarks>
6599+
<altmember cref="M:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8(System.String)" />
65926600
</Docs>
65936601
</Member>
65946602
<Member MemberName="PtrToStringUTF8">
@@ -6626,11 +6634,19 @@ There is a difference in the behavior of the `GetLastWin32Error` method on .NET
66266634
<Parameter Name="byteLen" Type="System.Int32" Index="1" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1" />
66276635
</Parameters>
66286636
<Docs>
6629-
<param name="ptr">To be added.</param>
6630-
<param name="byteLen">To be added.</param>
6631-
<summary>To be added.</summary>
6632-
<returns>To be added.</returns>
6633-
<remarks>To be added.</remarks>
6637+
<param name="ptr">The address of the first character of the unmanaged string.</param>
6638+
<param name="byteLen">The number of bytes to copy.</param>
6639+
<summary>Allocates a managed <see cref="T:System.String" /> and copies a specified number of bytes from an unmanaged UTF8 string into it.</summary>
6640+
<returns>A managed string that holds a copy of the unmanaged string if the value of the <paramref name="ptr" /> parameter is not <see langword="null" />; otherwise, this method returns <see langword="null" />.</returns>
6641+
<remarks>
6642+
<format type="text/markdown"><![CDATA[
6643+
6644+
## Remarks
6645+
<xref:System.Runtime.InteropServices.Marshal.PtrToStringUTF8%2A> is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the <xref:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8%2A?displayProperty=nameWithType> methods.
6646+
6647+
]]></format>
6648+
</remarks>
6649+
<altmember cref="M:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8(System.String)" />
66346650
</Docs>
66356651
</Member>
66366652
<MemberGroup MemberName="PtrToStructure">
@@ -9477,10 +9493,22 @@ There is a difference in the behavior of the `GetLastWin32Error` method on .NET
94779493
<Parameter Name="s" Type="System.String" Index="0" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1" />
94789494
</Parameters>
94799495
<Docs>
9480-
<param name="s">To be added.</param>
9481-
<summary>To be added.</summary>
9482-
<returns>To be added.</returns>
9483-
<remarks>To be added.</remarks>
9496+
<param name="s">A managed string to be copied.</param>
9497+
<summary>Copies the contents of a managed <see cref="T:System.String" /> to a block of memory allocated from the unmanaged COM task allocator.</summary>
9498+
<returns>An integer representing a pointer to the block of memory allocated for the string, or 0 if <paramref name="s" /> is <see langword="null" />.</returns>
9499+
<remarks>
9500+
<format type="text/markdown"><![CDATA[
9501+
9502+
## Remarks
9503+
<xref:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8%2A> is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string including a null terminator, always free the memory by calling <xref:System.Runtime.InteropServices.Marshal.FreeCoTaskMem%2A?displayProperty=nameWithType>. This method provides the opposite functionality of <xref:System.Runtime.InteropServices.Marshal.PtrToStringUTF8%2A?displayProperty=nameWithType>. The characters of the string are copied as UTF-8 characters.
9504+
9505+
]]></format>
9506+
</remarks>
9507+
<exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="s" /> parameter exceeds the maximum length allowed by the operating system.</exception>
9508+
<exception cref="T:System.OutOfMemoryException">There is insufficient memory available.</exception>
9509+
<altmember cref="M:System.Runtime.InteropServices.Marshal.FreeCoTaskMem(System.IntPtr)" />
9510+
<altmember cref="M:System.Runtime.InteropServices.Marshal.ZeroFreeCoTaskMemUTF8(System.IntPtr)" />
9511+
<altmember cref="M:System.Runtime.InteropServices.Marshal.PtrToStringUTF8(System.IntPtr,System.Int32)" />
94849512
</Docs>
94859513
</Member>
94869514
<Member MemberName="StringToHGlobalAnsi">
@@ -11871,9 +11899,16 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo)
1187111899
<Parameter Name="s" Type="System.IntPtr" Index="0" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1" />
1187211900
</Parameters>
1187311901
<Docs>
11874-
<param name="s">To be added.</param>
11875-
<summary>To be added.</summary>
11876-
<remarks>To be added.</remarks>
11902+
<param name="s">The address of the unmanaged string to free.</param>
11903+
<summary>Frees an unmanaged string pointer that was allocated using the <see cref="M:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8(System.String)" /> method.</summary>
11904+
<remarks>
11905+
<format type="text/markdown"><![CDATA[
11906+
11907+
## Remarks
11908+
The <xref:System.Runtime.InteropServices.Marshal.ZeroFreeCoTaskMemUTF8%2A> method first zeros out and then frees unmanaged memory that was allocated using the <xref:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8%2A> method.
11909+
11910+
]]></format>
11911+
</remarks>
1187711912
</Docs>
1187811913
</Member>
1187911914
<Member MemberName="ZeroFreeGlobalAllocAnsi">

‎xml/System.Runtime.InteropServices/SafeBuffer.xml

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -447,9 +447,19 @@ finally {
447447
<ReturnType>System.Boolean</ReturnType>
448448
</ReturnValue>
449449
<Docs>
450-
<summary>To be added.</summary>
451-
<value>To be added.</value>
452-
<remarks>To be added.</remarks>
450+
<summary>Gets a value that indicates whether the handle is invalid.</summary>
451+
<value>
452+
<see langword="true" /> if the handle is not valid; otherwise, <see langword="false" />.</value>
453+
<remarks>
454+
<format type="text/markdown"><![CDATA[
455+
456+
## Remarks
457+
The common language runtime uses this property to determine whether critical finalization is required.
458+
459+
]]></format>
460+
</remarks>
461+
<altmember cref="P:Microsoft.Win32.SafeHandles.SafeHandleMinusOneIsInvalid.IsInvalid" />
462+
<altmember cref="T:Microsoft.Win32.SafeHandles.SafeHandleMinusOneIsInvalid" />
453463
</Docs>
454464
</Member>
455465
<Member MemberName="Read&lt;T&gt;">

‎xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`2.xml

Lines changed: 57 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -256,7 +256,7 @@
256256
<returns>An IDisposable that, upon calling Dispose, will unlink the source from the target.</returns>
257257
<remarks>To be added.</remarks>
258258
<exception cref="T:System.ArgumentNullException">
259-
<paramref name="target" /> is null (Nothing in Visual Basic) or <paramref name="linkOptions" /> is null (Nothing in Visual Basic).</exception>
259+
<paramref name="target" /> is <see langword="null" /> (Nothing in Visual Basic) or <paramref name="linkOptions" /> is <see langword="null" /> (Nothing in Visual Basic).</exception>
260260
</Docs>
261261
</Member>
262262
<Member MemberName="OutputCount">
@@ -353,12 +353,25 @@ After `Fault` has been called on a dataflow block, that block will complete, suc
353353
<Parameter Name="messageConsumed" Type="System.Boolean" RefType="out" />
354354
</Parameters>
355355
<Docs>
356-
<param name="messageHeader">To be added.</param>
357-
<param name="target">To be added.</param>
358-
<param name="messageConsumed">To be added.</param>
359-
<summary>To be added.</summary>
360-
<returns>To be added.</returns>
361-
<remarks>To be added.</remarks>
356+
<param name="messageHeader">The <see cref="T:System.Threading.Tasks.Dataflow.DataflowMessageHeader" /> of the message that is to be consumed.</param>
357+
<param name="target">The <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" /> for which the message is to be consumed.</param>
358+
<param name="messageConsumed">
359+
<see langword="true" /> if the message was successfully consumed. <see langword="false" /> otherwise.</param>
360+
<summary>Passes the ownership of the message identified by the <see cref="T:System.Threading.Tasks.Dataflow.DataflowMessageHeader" /> from this <see cref="T:System.Threading.Tasks.Dataflow.ISourceBlock`1" /> instance to the <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" />.</summary>
361+
<returns> The value of the consumed message. This may correspond to a different <see cref="T:System.Threading.Tasks.Dataflow.DataflowMessageHeader" /> instance than was previously reserved and passed as the <paramref name="messageHeader" /> to <see cref="M:ConsumeMessage" />. The consuming <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" /> must use the returned value instead of the value passed as messageValue through <see cref="M:OfferMessage" />.
362+
If the message requested is not available, the return value will be <see langword="null" /> (Nothing in Visual Basic).
363+
</returns>
364+
<remarks>
365+
<format type="text/markdown"><![CDATA[
366+
367+
## Remarks
368+
369+
The <xref:System.Threading.Tasks.Dataflow.ITargetBlock`1> for which the message is to be consumed need not be linked from this <xref:System.Threading.Tasks.Dataflow.ISourceBlock`1> instance. Moreover, this <xref:System.Threading.Tasks.Dataflow.ISourceBlock`1> instance may have never offered the message directly to the <xref:System.Threading.Tasks.Dataflow.ITargetBlock`1>.
370+
371+
]]></format>
372+
</remarks>
373+
<exception cref="T:System.ArgumentException">The <paramref name="messageHeader" /> is not valid.</exception>
374+
<exception cref="T:System.ArgumentNullException">The <paramref name="target" /> is <see langword="null" /> (Nothing in Visual Basic).</exception>
362375
</Docs>
363376
</Member>
364377
<Member MemberName="System.Threading.Tasks.Dataflow.ISourceBlock&lt;System.Tuple&lt;System.Collections.Generic.IList&lt;T1&gt;,System.Collections.Generic.IList&lt;T2&gt;&gt;&gt;.ReleaseReservation">
@@ -389,10 +402,23 @@ After `Fault` has been called on a dataflow block, that block will complete, suc
389402
<Parameter Name="target" Type="System.Threading.Tasks.Dataflow.ITargetBlock&lt;System.Tuple&lt;System.Collections.Generic.IList&lt;T1&gt;,System.Collections.Generic.IList&lt;T2&gt;&gt;&gt;" />
390403
</Parameters>
391404
<Docs>
392-
<param name="messageHeader">To be added.</param>
393-
<param name="target">To be added.</param>
394-
<summary>To be added.</summary>
395-
<remarks>To be added.</remarks>
405+
<param name="messageHeader">The <see cref="T:System.Threading.Tasks.Dataflow.DataflowMessageHeader" /> of the reserved message.</param>
406+
<param name="target">The <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" /> that currently holds the reservation.</param>
407+
<summary>Releases the right to pass the ownership of the message identified by the <see cref="T:System.Threading.Tasks.Dataflow.DataflowMessageHeader" /> from this <see cref="T:System.Threading.Tasks.Dataflow.ISourceBlock`1" /> to the <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" />.</summary>
408+
<remarks>
409+
<format type="text/markdown"><![CDATA[
410+
411+
## Remarks
412+
413+
The <xref:System.Threading.Tasks.Dataflow.ITargetBlock`1> that holds the reservation need not be linked from this <xref:System.Threading.Tasks.Dataflow.ISourceBlock`1> instance. Moreover, this <xref:System.Threading.Tasks.Dataflow.ISourceBlock`1> instance may have never offered the message directly to the <xref:System.Threading.Tasks.Dataflow.ITargetBlock`1>.
414+
It is required that this message has been previously reserved for the same <xref:System.Threading.Tasks.Dataflow.ITargetBlock`1>.
415+
416+
417+
]]></format>
418+
</remarks>
419+
<exception cref="T:System.ArgumentException">The <paramref name="messageHeader" /> is not valid.</exception>
420+
<exception cref="T:System.ArgumentNullException">The <paramref name="target" /> is <see langword="null" /> (Nothing in Visual Basic).</exception>
421+
<exception cref="T:System.InvalidOperationException">The <paramref name="target" /> did not have the message reserved.</exception>
396422
</Docs>
397423
</Member>
398424
<Member MemberName="System.Threading.Tasks.Dataflow.ISourceBlock&lt;System.Tuple&lt;System.Collections.Generic.IList&lt;T1&gt;,System.Collections.Generic.IList&lt;T2&gt;&gt;&gt;.ReserveMessage">
@@ -423,11 +449,26 @@ After `Fault` has been called on a dataflow block, that block will complete, suc
423449
<Parameter Name="target" Type="System.Threading.Tasks.Dataflow.ITargetBlock&lt;System.Tuple&lt;System.Collections.Generic.IList&lt;T1&gt;,System.Collections.Generic.IList&lt;T2&gt;&gt;&gt;" />
424450
</Parameters>
425451
<Docs>
426-
<param name="messageHeader">To be added.</param>
427-
<param name="target">To be added.</param>
428-
<summary>To be added.</summary>
429-
<returns>To be added.</returns>
430-
<remarks>To be added.</remarks>
452+
<param name="messageHeader">The <see cref="T:System.Threading.Tasks.Dataflow.DataflowMessageHeader" /> of the message that is to be reserved.</param>
453+
<param name="target">The <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" /> for which the message is to be reserved.</param>
454+
<summary>Reserves the right to pass the ownership of the message identified by the <see cref="T:System.Threading.Tasks.Dataflow.DataflowMessageHeader" /> from this <see cref="T:System.Threading.Tasks.Dataflow.ISourceBlock`1" /> to the <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" />.</summary>
455+
<returns>
456+
<see langword="true" /> if the message was successfully reserved; otherwise, <see langword="false" />.</returns>
457+
<remarks>
458+
<format type="text/markdown"><![CDATA[
459+
460+
## Remarks
461+
462+
The <xref:System.Threading.Tasks.Dataflow.ITargetBlock`1> for which the message is to be reserved need not be linked from this <xref:System.Threading.Tasks.Dataflow.ISourceBlock`1> instance. Moreover, this <xref:System.Threading.Tasks.Dataflow.ISourceBlock`1> instance may have never offered the message directly to the <xref:System.Threading.Tasks.Dataflow.ITargetBlock`1>.
463+
If `true` is returned, either <xref:ConsumeMessage> or <xref:ReleaseReservation> for this message must be subsequently called with the same <xref:System.Threading.Tasks.Dataflow.DataflowMessageHeader> and <xref:System.Threading.Tasks.Dataflow.ITargetBlock`1>.
464+
Failure to do so may result in the source being unable to propagate any further messages to any target.
465+
<xref:ReserveMessage> must not be called while the target is holding any internal locks. Doing so will violate the lock hierarchy necessary to avoid deadlocks in a dataflow network.
466+
467+
468+
]]></format>
469+
</remarks>
470+
<exception cref="T:System.ArgumentException">The <paramref name="messageHeader" /> is not valid.</exception>
471+
<exception cref="T:System.ArgumentNullException">The <paramref name="target" /> is <see langword="null" /> (Nothing in Visual Basic).</exception>
431472
</Docs>
432473
</Member>
433474
<Member MemberName="Target1">

0 commit comments

Comments
 (0)