Skip to content

Commit edc3fab

Browse files
carlossanlopgewarren
carlossanlop
and
gewarren
authored
Automatically port 5.0 System.Runtime.InteropServices documentation (dotnet#4286)
* Automatically port 5.0 System.Runtime.InteropServices documentation * Apply suggestions from code review * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> * remove remark exception Co-authored-by: Genevieve Warren <[email protected]>
1 parent 4e30cc6 commit edc3fab

8 files changed

+140
-52
lines changed

‎xml/System.Runtime.InteropServices/CollectionsMarshal.xml

Lines changed: 3 additions & 2 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>An unsafe class that provides a set of methods to access the underlying data representations of collections.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -42,7 +42,8 @@
4242
<Docs>
4343
<typeparam name="T">To be added.</typeparam>
4444
<param name="list">To be added.</param>
45-
<summary>To be added.</summary>
45+
<summary>Gets a <see cref="T:System.Span`1" /> view over the data in a list.
46+
Items should not be added or removed from the <see cref="T:System.Collections.Generic.List`1" /> while the <see cref="T:System.Span`1" /> is in use.</summary>
4647
<returns>To be added.</returns>
4748
<remarks>To be added.</remarks>
4849
</Docs>

‎xml/System.Runtime.InteropServices/ComWrappers+ComInterfaceDispatch.xml

Lines changed: 5 additions & 5 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>An application binary interface for function dispatch of a COM interface.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -43,10 +43,10 @@
4343
<Parameter Name="dispatchPtr" Type="System.Runtime.InteropServices.ComWrappers+ComInterfaceDispatch*" />
4444
</Parameters>
4545
<Docs>
46-
<typeparam name="T">To be added.</typeparam>
47-
<param name="dispatchPtr">To be added.</param>
48-
<summary>To be added.</summary>
49-
<returns>To be added.</returns>
46+
<typeparam name="T">Desired type.</typeparam>
47+
<param name="dispatchPtr">Pointer to Vtable function entry.</param>
48+
<summary>Given an <see cref="T:System.IntPtr" /> from a generated Vtable, converts it to the target type.</summary>
49+
<returns>An instance of the type associated with the dispatched function call.</returns>
5050
<remarks>To be added.</remarks>
5151
</Docs>
5252
</Member>

‎xml/System.Runtime.InteropServices/ComWrappers+ComInterfaceEntry.xml

Lines changed: 12 additions & 4 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>Interface type and pointer to targeted VTable.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -34,7 +34,7 @@
3434
<ReturnType>System.Guid</ReturnType>
3535
</ReturnValue>
3636
<Docs>
37-
<summary>To be added.</summary>
37+
<summary>Interface identifier.</summary>
3838
<remarks>To be added.</remarks>
3939
</Docs>
4040
</Member>
@@ -54,8 +54,16 @@
5454
<ReturnType>System.IntPtr</ReturnType>
5555
</ReturnValue>
5656
<Docs>
57-
<summary>To be added.</summary>
58-
<remarks>To be added.</remarks>
57+
<summary>A pointer to the virtual lookup table of functions.</summary>
58+
<remarks>
59+
<format type="text/markdown"><![CDATA[
60+
61+
## Remarks
62+
63+
Memory must have the same lifetime as the memory returned from the call to <xref:System.Runtime.InteropServices.ComWrappers.ComputeVtables(System.Object,System.Runtime.InteropServices.CreateComInterfaceFlags,System.Int32@)>.
64+
65+
]]></format>
66+
</remarks>
5967
</Docs>
6068
</Member>
6169
</Members>

‎xml/System.Runtime.InteropServices/ComWrappers.xml

Lines changed: 51 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
</Attribute>
2121
</Attributes>
2222
<Docs>
23-
<summary>To be added.</summary>
23+
<summary>Class for managing wrappers of COM IUnknown types.</summary>
2424
<remarks>To be added.</remarks>
2525
</Docs>
2626
<Members>
@@ -61,12 +61,23 @@
6161
<Parameter Name="count" Type="System.Int32" RefType="out" />
6262
</Parameters>
6363
<Docs>
64-
<param name="obj">To be added.</param>
65-
<param name="flags">To be added.</param>
66-
<param name="count">To be added.</param>
67-
<summary>To be added.</summary>
68-
<returns>To be added.</returns>
69-
<remarks>To be added.</remarks>
64+
<param name="obj">Target of the returned Vtables.</param>
65+
<param name="flags">Flags used to compute Vtables.</param>
66+
<param name="count">The number of elements contained in the returned memory.</param>
67+
<summary>Computes the desired Vtable for <paramref name="obj" />, respecting the values of <paramref name="flags" />.</summary>
68+
<returns>
69+
<see cref="T:System.Runtime.InteropServices.ComWrappers.ComInterfaceEntry" /> pointer containing memory for all COM interface entries.</returns>
70+
<remarks>
71+
<format type="text/markdown"><![CDATA[
72+
73+
## Remarks
74+
75+
All memory returned from this function must either be unmanaged memory or pinned managed memory, or have been allocated with the <xref:System.Runtime.CompilerServices.RuntimeHelpers.AllocateTypeAssociatedMemory(System.Type,System.Int32)> API.
76+
77+
If the interface entries cannot be created and a negative `count` or `null` and a non-zero `count` are returned, the call to <xref:System.Runtime.InteropServices.ComWrappers.GetOrCreateComInterfaceForObject(System.Object,System.Runtime.InteropServices.CreateComInterfaceFlags)> will throw a <xref:System.ArgumentException>.
78+
79+
]]></format>
80+
</remarks>
7081
</Docs>
7182
</Member>
7283
<Member MemberName="CreateObject">
@@ -89,11 +100,19 @@
89100
<Parameter Name="flags" Type="System.Runtime.InteropServices.CreateObjectFlags" />
90101
</Parameters>
91102
<Docs>
92-
<param name="externalComObject">To be added.</param>
93-
<param name="flags">To be added.</param>
94-
<summary>To be added.</summary>
95-
<returns>To be added.</returns>
96-
<remarks>To be added.</remarks>
103+
<param name="externalComObject">Object to import for usage into the .NET runtime.</param>
104+
<param name="flags">Flags used to describe the external object.</param>
105+
<summary>Creates a managed object for the object that <paramref name="externalComObject" /> points to, respecting the values of <paramref name="flags" />.</summary>
106+
<returns>A managed object associated with the supplied external COM object.</returns>
107+
<remarks>
108+
<format type="text/markdown"><![CDATA[
109+
110+
## Remarks
111+
112+
If the object cannot be created and `null` is returned, the call to <xref:System.Runtime.InteropServices.ComWrappers.GetOrCreateObjectForComInstance(System.IntPtr,System.Runtime.InteropServices.CreateObjectFlags)> will throw a <xref:System.ArgumentNullException>.
113+
114+
]]></format>
115+
</remarks>
97116
</Docs>
98117
</Member>
99118
<Member MemberName="GetIUnknownImpl">
@@ -117,10 +136,10 @@
117136
<Parameter Name="fpRelease" Type="System.IntPtr" RefType="out" />
118137
</Parameters>
119138
<Docs>
120-
<param name="fpQueryInterface">To be added.</param>
121-
<param name="fpAddRef">To be added.</param>
122-
<param name="fpRelease">To be added.</param>
123-
<summary>To be added.</summary>
139+
<param name="fpQueryInterface">Function pointer to QueryInterface.</param>
140+
<param name="fpAddRef">Function pointer to AddRef.</param>
141+
<param name="fpRelease">Function pointer to Release.</param>
142+
<summary>Gets the runtime-provided IUnknown implementation.</summary>
124143
<remarks>To be added.</remarks>
125144
</Docs>
126145
</Member>
@@ -144,10 +163,10 @@
144163
<Parameter Name="flags" Type="System.Runtime.InteropServices.CreateComInterfaceFlags" />
145164
</Parameters>
146165
<Docs>
147-
<param name="instance">To be added.</param>
148-
<param name="flags">To be added.</param>
149-
<summary>To be added.</summary>
150-
<returns>To be added.</returns>
166+
<param name="instance">The managed object to expose outside the .NET runtime.</param>
167+
<param name="flags">Flags used to configure the generated interface.</param>
168+
<summary>Creates a COM representation of the supplied object that can be passed to a non-managed environment.</summary>
169+
<returns>The generated COM interface that can be passed outside the .NET runtime.</returns>
151170
<remarks>To be added.</remarks>
152171
</Docs>
153172
</Member>
@@ -171,10 +190,10 @@
171190
<Parameter Name="flags" Type="System.Runtime.InteropServices.CreateObjectFlags" />
172191
</Parameters>
173192
<Docs>
174-
<param name="externalComObject">To be added.</param>
175-
<param name="flags">To be added.</param>
176-
<summary>To be added.</summary>
177-
<returns>To be added.</returns>
193+
<param name="externalComObject">Object to import for usage into the .NET runtime.</param>
194+
<param name="flags">Flags used to describe the external object.</param>
195+
<summary>Gets the currently registered managed object or creates a new managed object and registers it.</summary>
196+
<returns>A managed object associated with the supplied external COM object.</returns>
178197
<remarks>To be added.</remarks>
179198
</Docs>
180199
</Member>
@@ -199,12 +218,13 @@
199218
<Parameter Name="wrapper" Type="System.Object" />
200219
</Parameters>
201220
<Docs>
202-
<param name="externalComObject">To be added.</param>
203-
<param name="flags">To be added.</param>
204-
<param name="wrapper">To be added.</param>
205-
<summary>To be added.</summary>
206-
<returns>To be added.</returns>
221+
<param name="externalComObject">Object to import for usage into the .NET runtime.</param>
222+
<param name="flags">Flags used to describe the external object.</param>
223+
<param name="wrapper">The object to use as the wrapper for the external object.</param>
224+
<summary>Gets the currently registered managed object or uses the supplied managed object and registers it.</summary>
225+
<returns>A managed object associated with the supplied external COM object.</returns>
207226
<remarks>To be added.</remarks>
227+
<exception cref="T:System.NotSupportedException">The wrapper instance is already associated with an external object.</exception>
208228
</Docs>
209229
</Member>
210230
<Member MemberName="RegisterForMarshalling">
@@ -274,8 +294,8 @@
274294
<Parameter Name="objects" Type="System.Collections.IEnumerable" />
275295
</Parameters>
276296
<Docs>
277-
<param name="objects">To be added.</param>
278-
<summary>To be added.</summary>
297+
<param name="objects">Collection of objects to release.</param>
298+
<summary>Releases a collection of objects outside of the normal object or COM interface lifetime.</summary>
279299
<remarks>To be added.</remarks>
280300
</Docs>
281301
</Member>

‎xml/System.Runtime.InteropServices/CreateComInterfaceFlags.xml

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
</Attribute>
2020
</Attributes>
2121
<Docs>
22-
<summary>To be added.</summary>
22+
<summary>Specifies flags for the <see cref="M:System.Runtime.InteropServices.ComWrappers.GetOrCreateComInterfaceForObject(System.Object,System.Runtime.InteropServices.CreateComInterfaceFlags)" /> method.</summary>
2323
<remarks>To be added.</remarks>
2424
</Docs>
2525
<Members>
@@ -40,7 +40,16 @@
4040
</ReturnValue>
4141
<MemberValue>1</MemberValue>
4242
<Docs>
43-
<summary>To be added.</summary>
43+
<summary>The caller will provide an IUnknown Vtable.</summary>
44+
<remarks>
45+
<format type="text/markdown"><![CDATA[
46+
47+
## Remarks
48+
49+
This flag is useful in scenarios when the caller has no need to rely on an IUnknown instance that's used when it's not possible to run managed code (that is, during a garbage collection). This is common in traditional COM scenarios, but scenarios where <see href="/windows/win32/api/windows.ui.xaml.hosting.referencetracker/nn-windows-ui-xaml-hosting-referencetracker-ireferencetrackertarget">Reference Tracker hosting</see> calls the IUnknown API during a garbage collection are possible.
50+
51+
]]></format>
52+
</remarks>
4453
</Docs>
4554
</Member>
4655
<Member MemberName="None">
@@ -80,7 +89,16 @@
8089
</ReturnValue>
8190
<MemberValue>2</MemberValue>
8291
<Docs>
83-
<summary>To be added.</summary>
92+
<summary>Flag used to indicate the COM interface should implement <see href="https://docs.microsoft.com/windows/win32/api/windows.ui.xaml.hosting.referencetracker/nn-windows-ui-xaml-hosting-referencetracker-ireferencetrackertarget">IReferenceTrackerTarget</see>.</summary>
93+
<remarks>
94+
<format type="text/markdown"><![CDATA[
95+
96+
## Remarks
97+
98+
When this flag is passed, the resulting COM interface will have an internal implementation of [IUnknown](https://docs.microsoft.com/windows/win32/api/unknwn/nn-unknwn-iunknown), therefore, none should be supplied by the caller.
99+
100+
]]></format>
101+
</remarks>
84102
</Docs>
85103
</Member>
86104
</Members>

‎xml/System.Runtime.InteropServices/CreateObjectFlags.xml

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
</Attribute>
2020
</Attributes>
2121
<Docs>
22-
<summary>To be added.</summary>
22+
<summary>Specifies flags for the <see cref="M:System.Runtime.InteropServices.ComWrappers.GetOrCreateObjectForComInstance(System.IntPtr,System.Runtime.InteropServices.CreateObjectFlags)" /> method.</summary>
2323
<remarks>To be added.</remarks>
2424
</Docs>
2525
<Members>
@@ -60,7 +60,8 @@
6060
</ReturnValue>
6161
<MemberValue>1</MemberValue>
6262
<Docs>
63-
<summary>To be added.</summary>
63+
<summary>Indicates that the supplied external COM object implements the <see href="https://docs.microsoft.com/windows/win32/api/windows.ui.xaml.hosting.referencetracker/nn-windows-ui-xaml-hosting-referencetracker-ireferencetracker">IReferenceTracker</see>.</summary>
64+
<remarks>To be added.</remarks>
6465
</Docs>
6566
</Member>
6667
<Member MemberName="UniqueInstance">
@@ -80,7 +81,8 @@
8081
</ReturnValue>
8182
<MemberValue>2</MemberValue>
8283
<Docs>
83-
<summary>To be added.</summary>
84+
<summary>Indicates to ignore internal caching and always create a unique instance.</summary>
85+
<remarks>To be added.</remarks>
8486
</Docs>
8587
</Member>
8688
</Members>

‎xml/System.Runtime.InteropServices/RuntimeInformation.xml

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -265,9 +265,20 @@
265265
<ReturnType>System.String</ReturnType>
266266
</ReturnValue>
267267
<Docs>
268-
<summary>To be added.</summary>
268+
<summary>Returns an opaque string that identifies the platform on which an app is running.</summary>
269269
<value>To be added.</value>
270-
<remarks>To be added.</remarks>
270+
<remarks>
271+
<format type="text/markdown"><![CDATA[
272+
273+
## Remarks
274+
275+
This property returns a string that identifies the operating system, typically including the version and processor architecture of the currently executing process.
276+
Since this string is opaque, it is not recommended to parse the string into its constituent parts.
277+
278+
For more information, see https://docs.microsoft.com/dotnet/core/rid-catalog.
279+
280+
]]></format>
281+
</remarks>
271282
</Docs>
272283
</Member>
273284
</Members>

‎xml/System.Runtime.InteropServices/SuppressGCTransitionAttribute.xml

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,36 @@
2020
</Attribute>
2121
</Attributes>
2222
<Docs>
23-
<summary>To be added.</summary>
24-
<remarks>To be added.</remarks>
23+
<summary>Indicates that a garbage collection transition should be skipped when an unmanaged function call is made.</summary>
24+
<remarks>
25+
<format type="text/markdown"><![CDATA[
26+
27+
## Remarks
28+
29+
This attribute is ignored if applied to a method without the <xref:System.Runtime.InteropServices.DllImportAttribute>.
30+
31+
Forgoing this transition can yield benefits when the cost of the transition is more than the execution time of the unmanaged function. However, avoiding this transition removes some of the guarantees the runtime provides through a normal P/Invoke. When exiting the managed runtime to enter an unmanaged function, the GC must transition from Cooperative mode into Preemptive mode. Full details on these modes can be found at https://github.com/dotnet/runtime/blob/master/docs/coding-guidelines/clr-code-guide.md#2.1.8.
32+
Suppressing the GC transition is an advanced scenario and should not be done without fully understanding potential consequences.
33+
34+
One of these consequences is an impact to [Mixed-mode debugging](https://docs.microsoft.com/visualstudio/debugger/how-to-debug-in-mixed-mode).
35+
During Mixed-mode debugging, it is not possible to step into or set breakpoints in a P/Invoke that has been marked with this attribute. A workaround is to switch to native debugging and set a breakpoint in the native function.
36+
In general, usage of this attribute is not recommended if debugging the P/Invoke is important, for example, stepping through the native code or diagnosing an exception thrown from the native code.
37+
38+
The P/Invoke method that this attribute is applied to must have all of the following properties:
39+
* Native function always executes for a trivial amount of time (less than 1 microsecond).
40+
* Native function does not perform a blocking syscall (for example, any type of I/O).
41+
* Native function does not call back into the runtime (for example, Reverse P/Invoke).
42+
* Native function does not throw exceptions.
43+
* Native function does not manipulate locks or other concurrency primitives.
44+
45+
Consequences of invalid uses of this attribute include:
46+
47+
* GC starvation.
48+
* Immediate runtime termination.
49+
* Data corruption.
50+
51+
]]></format>
52+
</remarks>
2553
</Docs>
2654
<Members>
2755
<Member MemberName=".ctor">

0 commit comments

Comments
 (0)