Skip to content

Commit 8bd248a

Browse files
carlossanlopcarlossanlop
authored
Port System.Runtime.InteropServices new docs (#10154)
* System.Runtime.InteropServices * System.Runtime.InteropServices.Marshalling * System.Runtime.InteropServices.Swift
1 parent edeee5d commit 8bd248a

File tree

11 files changed

+114
-81
lines changed

11 files changed

+114
-81
lines changed

‎xml/System.Runtime.InteropServices.Marshalling/ComVariant.xml

Lines changed: 25 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
</Interface>
1919
</Interfaces>
2020
<Docs>
21-
<summary>To be added.</summary>
21+
<summary>A type that represents an OLE VARIANT in managed code.</summary>
2222
<remarks>To be added.</remarks>
2323
</Docs>
2424
<Members>
@@ -52,10 +52,11 @@
5252
</TypeParameters>
5353
<Parameters />
5454
<Docs>
55-
<typeparam name="T">To be added.</typeparam>
56-
<summary>To be added.</summary>
57-
<returns>To be added.</returns>
55+
<typeparam name="T">The managed type to create an instance of.</typeparam>
56+
<summary>Create a managed value based on the value in the <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" /> instance.</summary>
57+
<returns>The managed value contained in this variant.</returns>
5858
<remarks>To be added.</remarks>
59+
<exception cref="T:System.ArgumentException">When <typeparamref name="T" /> does not match the <see cref="P:System.Runtime.InteropServices.Marshalling.ComVariant.VarType" /> of the <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" />.</exception>
5960
</Docs>
6061
</Member>
6162
<Member MemberName="Create&lt;T&gt;">
@@ -100,11 +101,12 @@
100101
</Parameter>
101102
</Parameters>
102103
<Docs>
103-
<typeparam name="T">To be added.</typeparam>
104-
<param name="value">To be added.</param>
105-
<summary>To be added.</summary>
106-
<returns>To be added.</returns>
104+
<typeparam name="T">The type of the specified value.</typeparam>
105+
<param name="value">The value to wrap in an <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" />.</param>
106+
<summary>Create an <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" /> instance from the specified value.</summary>
107+
<returns>An <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" /> that contains the provided value.</returns>
107108
<remarks>To be added.</remarks>
109+
<exception cref="T:System.ArgumentException">When <typeparamref name="T" /> does not directly correspond to a <see cref="T:System.Runtime.InteropServices.VarEnum" /> variant type.</exception>
108110
</Docs>
109111
</Member>
110112
<Member MemberName="CreateRaw&lt;T&gt;">
@@ -142,12 +144,14 @@
142144
<Parameter Name="rawValue" Type="T" />
143145
</Parameters>
144146
<Docs>
145-
<typeparam name="T">To be added.</typeparam>
146-
<param name="vt">To be added.</param>
147-
<param name="rawValue">To be added.</param>
148-
<summary>To be added.</summary>
149-
<returns>To be added.</returns>
147+
<typeparam name="T">The type of the value to store in the variant.</typeparam>
148+
<param name="vt">The type of the variant</param>
149+
<param name="rawValue">The raw value to store in the variant without any processing</param>
150+
<summary>Create a <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" /> with the given type and provided value.</summary>
151+
<returns>A variant that contains the provided value.</returns>
150152
<remarks>To be added.</remarks>
153+
<exception cref="T:System.ArgumentException">When the provided <paramref name="vt" /> corresponds to a variant type that is not supported in VARIANTs or is <see cref="F:System.Runtime.InteropServices.VarEnum.VT_DECIMAL" /></exception>
154+
<exception cref="T:System.PlatformNotSupportedException">When the provided <paramref name="vt" /> specifies the <see cref="F:System.Runtime.InteropServices.VarEnum.VT_ARRAY" /> flag for SAFEARRAYs.</exception>
151155
</Docs>
152156
</Member>
153157
<Member MemberName="Dispose">
@@ -170,7 +174,7 @@
170174
</ReturnValue>
171175
<Parameters />
172176
<Docs>
173-
<summary>To be added.</summary>
177+
<summary>Release resources owned by this <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" /> instance.</summary>
174178
<remarks>To be added.</remarks>
175179
</Docs>
176180
</Member>
@@ -212,10 +216,12 @@
212216
</TypeParameters>
213217
<Parameters />
214218
<Docs>
215-
<typeparam name="T">To be added.</typeparam>
216-
<summary>To be added.</summary>
217-
<returns>To be added.</returns>
219+
<typeparam name="T">The type of reference to return.</typeparam>
220+
<summary>Get a reference to the storage location within this <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" /> instance.</summary>
221+
<returns>A reference to the storage location within this <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" />.</returns>
218222
<remarks>To be added.</remarks>
223+
<exception cref="T:System.ArgumentException">
224+
<typeparamref name="T" /> is <see cref="T:System.Decimal" /> or larger than the storage space in an <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" />.</exception>
219225
</Docs>
220226
</Member>
221227
<Member MemberName="Null">
@@ -234,7 +240,7 @@
234240
<ReturnType>System.Runtime.InteropServices.Marshalling.ComVariant</ReturnType>
235241
</ReturnValue>
236242
<Docs>
237-
<summary>To be added.</summary>
243+
<summary>A <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" /> instance that represents a <see langword="null" /> value with <see cref="F:System.Runtime.InteropServices.VarEnum.VT_NULL" /> type.</summary>
238244
<value>To be added.</value>
239245
<remarks>To be added.</remarks>
240246
</Docs>
@@ -261,7 +267,7 @@
261267
<ReturnType>System.Runtime.InteropServices.VarEnum</ReturnType>
262268
</ReturnValue>
263269
<Docs>
264-
<summary>To be added.</summary>
270+
<summary>The type of the data stored in this <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" />.</summary>
265271
<value>To be added.</value>
266272
<remarks>To be added.</remarks>
267273
</Docs>

‎xml/System.Runtime.InteropServices.Marshalling/ComVariantMarshaller+RefPropagate.xml

Lines changed: 11 additions & 10 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>Marshals a <see cref="T:System.Object" /> to an <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" />, propagating the value of the <see cref="T:System.Object" /> back to the variant's existing data storage if the variant has <see cref="F:System.Runtime.InteropServices.VarEnum.VT_BYREF" /> type.</summary>
2424
<remarks>To be added.</remarks>
2525
</Docs>
2626
<Members>
@@ -41,7 +41,7 @@
4141
</ReturnValue>
4242
<Parameters />
4343
<Docs>
44-
<summary>To be added.</summary>
44+
<summary>Free all resources owned by the marshaller.</summary>
4545
<remarks>To be added.</remarks>
4646
</Docs>
4747
</Member>
@@ -64,8 +64,8 @@
6464
<Parameter Name="managed" Type="System.Object" />
6565
</Parameters>
6666
<Docs>
67-
<param name="managed">To be added.</param>
68-
<summary>To be added.</summary>
67+
<param name="managed">The managed object.</param>
68+
<summary>Initializes the marshaller with a managed object.</summary>
6969
<remarks>To be added.</remarks>
7070
</Docs>
7171
</Member>
@@ -88,8 +88,8 @@
8888
<Parameter Name="unmanaged" Type="System.Runtime.InteropServices.Marshalling.ComVariant" />
8989
</Parameters>
9090
<Docs>
91-
<param name="unmanaged">To be added.</param>
92-
<summary>To be added.</summary>
91+
<param name="unmanaged">The unmanaged value</param>
92+
<summary>Initializes the marshaller with an unmanaged variant.</summary>
9393
<remarks>To be added.</remarks>
9494
</Docs>
9595
</Member>
@@ -110,8 +110,8 @@
110110
</ReturnValue>
111111
<Parameters />
112112
<Docs>
113-
<summary>To be added.</summary>
114-
<returns>To be added.</returns>
113+
<summary>Create the managed value based on the provided unmanaged value.</summary>
114+
<returns>The managed value corresponding to the VARIANT.</returns>
115115
<remarks>To be added.</remarks>
116116
</Docs>
117117
</Member>
@@ -132,9 +132,10 @@
132132
</ReturnValue>
133133
<Parameters />
134134
<Docs>
135-
<summary>To be added.</summary>
136-
<returns>To be added.</returns>
135+
<summary>Create an unmanaged <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" /> based on the provided managed and unmanaged values.</summary>
136+
<returns>An <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" /> instance representing the marshaller's current state.</returns>
137137
<remarks>To be added.</remarks>
138+
<exception cref="T:System.ArgumentException">When the managed value must be propagated back to the unmanaged variant, but the managed value type cannot be converted to the variant's type.</exception>
138139
</Docs>
139140
</Member>
140141
</Members>

‎xml/System.Runtime.InteropServices.Marshalling/ComVariantMarshaller.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@
3232
</Attribute>
3333
</Attributes>
3434
<Docs>
35-
<summary>To be added.</summary>
36-
<remarks>To be added.</remarks>
35+
<summary>Marshals an <see cref="T:System.Object" /> to an <see cref="T:System.Runtime.InteropServices.Marshalling.ComVariant" />.</summary>
36+
<remarks>Supports the same types as <see cref="M:System.Runtime.InteropServices.Marshalling.ComVariant.Create``1(``0)" /> as well as any types with <see cref="T:System.Runtime.InteropServices.Marshalling.GeneratedComClassAttribute" /> applied.</remarks>
3737
</Docs>
3838
<Members>
3939
<Member MemberName="ConvertToManaged">

‎xml/System.Runtime.InteropServices.Marshalling/ReadOnlySpanMarshaller`2+ManagedToUnmanagedOut.xml

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@
3737
</Base>
3838
<Interfaces />
3939
<Docs>
40-
<summary>To be added.</summary>
40+
<summary>Supports marshalling from unmanaged to managed in a call from managed code to unmanaged code. For example, return values and `out` parameters in P/Invoke methods.</summary>
4141
<remarks>To be added.</remarks>
4242
</Docs>
4343
<Members>
@@ -58,7 +58,7 @@
5858
</ReturnValue>
5959
<Parameters />
6060
<Docs>
61-
<summary>To be added.</summary>
61+
<summary>Frees resources.</summary>
6262
<remarks>To be added.</remarks>
6363
</Docs>
6464
</Member>
@@ -80,8 +80,8 @@
8080
<Parameter Name="unmanaged" Type="TUnmanagedElement*" />
8181
</Parameters>
8282
<Docs>
83-
<param name="unmanaged">To be added.</param>
84-
<summary>To be added.</summary>
83+
<param name="unmanaged">A pointer to the array to be unmarshalled from native to managed.</param>
84+
<summary>Initializes the <see cref="T:System.Runtime.InteropServices.Marshalling.ReadOnlySpanMarshaller`2.ManagedToUnmanagedOut" /> marshaller.</summary>
8585
<remarks>To be added.</remarks>
8686
</Docs>
8787
</Member>
@@ -111,8 +111,8 @@
111111
</Parameters>
112112
<Docs>
113113
<param name="numElements">To be added.</param>
114-
<summary>To be added.</summary>
115-
<returns>To be added.</returns>
114+
<summary>Returns a span that points to the memory where the managed elements of the array should be stored.</summary>
115+
<returns>A span where managed values of the array should be stored.</returns>
116116
<remarks>To be added.</remarks>
117117
</Docs>
118118
</Member>
@@ -136,8 +136,8 @@
136136
</Parameters>
137137
<Docs>
138138
<param name="numElements">To be added.</param>
139-
<summary>To be added.</summary>
140-
<returns>To be added.</returns>
139+
<summary>Returns a span that points to the memory where the unmanaged elements of the array are stored.</summary>
140+
<returns>A span over unmanaged values of the array.</returns>
141141
<remarks>To be added.</remarks>
142142
</Docs>
143143
</Member>
@@ -164,7 +164,7 @@
164164
</ReturnValue>
165165
<Parameters />
166166
<Docs>
167-
<summary>To be added.</summary>
167+
<summary>Returns the managed value representing the native array.</summary>
168168
<returns>To be added.</returns>
169169
<remarks>To be added.</remarks>
170170
</Docs>

‎xml/System.Runtime.InteropServices.Swift/SwiftError.xml

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,13 @@
2424
</Attribute>
2525
</Attributes>
2626
<Docs>
27-
<summary>To be added.</summary>
28-
<remarks>To be added.</remarks>
27+
<summary>Represents the Swift error context, indicating that the argument is the error context.</summary>
28+
<remarks>
29+
<para> This struct is used to retrieve the 'error' context from Swift functions in the context of interop with .NET.
30+
</para>
31+
<para> Here's an example of how a SwiftError can be declared:
32+
<code lang="csharp"> [UnmanagedCallConv(CallConvs = [typeof(CallConvSwift)])] [DllImport("SwiftLibrary", EntryPoint = "export")] public static extern void swiftFunction(SwiftError* error); </code></para>
33+
</remarks>
2934
</Docs>
3035
<Members>
3136
<Member MemberName=".ctor">
@@ -43,8 +48,8 @@
4348
<Parameter Name="value" Type="System.Void*" />
4449
</Parameters>
4550
<Docs>
46-
<param name="value">To be added.</param>
47-
<summary>To be added.</summary>
51+
<param name="value">The pointer value representing the error context.</param>
52+
<summary>Creates a new instance of the SwiftError struct with the specified pointer value.</summary>
4853
<remarks>To be added.</remarks>
4954
</Docs>
5055
</Member>
@@ -63,7 +68,7 @@
6368
<ReturnType>System.Void*</ReturnType>
6469
</ReturnValue>
6570
<Docs>
66-
<summary>To be added.</summary>
71+
<summary>Gets the pointer of the error context.</summary>
6772
<value>To be added.</value>
6873
<remarks>To be added.</remarks>
6974
</Docs>

‎xml/System.Runtime.InteropServices.Swift/SwiftIndirectResult.xml

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,15 @@
2424
</Attribute>
2525
</Attributes>
2626
<Docs>
27-
<summary>To be added.</summary>
28-
<remarks>To be added.</remarks>
27+
<summary>Represents the Swift return buffer context.</summary>
28+
<remarks>This struct is used to access the return buffer when interoping with Swift functions that return non-frozen structs.
29+
It provides a pointer to the memory location where the result should be stored.</remarks>
30+
<example>Here's an example of how a SwiftIndirectResult can be declared:
31+
<code lang="csharp">
32+
[UnmanagedCallConv(CallConvs = [typeof(CallConvSwift)])]
33+
[LibraryImport("SwiftLibrary", EntryPoint = "export")]
34+
public static extern void swiftFunction(SwiftIndirectResult result);
35+
</code></example>
2936
</Docs>
3037
<Members>
3138
<Member MemberName=".ctor">
@@ -43,8 +50,8 @@
4350
<Parameter Name="value" Type="System.Void*" />
4451
</Parameters>
4552
<Docs>
46-
<param name="value">To be added.</param>
47-
<summary>To be added.</summary>
53+
<param name="value">The pointer value representing return buffer context.</param>
54+
<summary>Creates a new instance of the SwiftIndirectResult struct with the specified pointer value.</summary>
4855
<remarks>To be added.</remarks>
4956
</Docs>
5057
</Member>
@@ -63,7 +70,7 @@
6370
<ReturnType>System.Void*</ReturnType>
6471
</ReturnValue>
6572
<Docs>
66-
<summary>To be added.</summary>
73+
<summary>Gets the pointer of the return buffer register.</summary>
6774
<value>To be added.</value>
6875
<remarks>To be added.</remarks>
6976
</Docs>

‎xml/System.Runtime.InteropServices.Swift/SwiftSelf.xml

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,13 @@
2424
</Attribute>
2525
</Attributes>
2626
<Docs>
27-
<summary>To be added.</summary>
28-
<remarks>To be added.</remarks>
27+
<summary>Represents the Swift 'self' context, indicating that the argument is the self context.</summary>
28+
<remarks>
29+
<para> This struct is used to pass the 'self' context to Swift functions in the context of interop with .NET.
30+
</para>
31+
<para> Here's an example of how a SwiftSelf context can be declared:
32+
<code lang="csharp"> [UnmanagedCallConv(CallConvs = [typeof(CallConvSwift)])] [DllImport("SwiftLibrary", EntryPoint = "export")] public static extern void swiftFunction(SwiftSelf self); </code></para>
33+
</remarks>
2934
</Docs>
3035
<Members>
3136
<Member MemberName=".ctor">
@@ -43,8 +48,8 @@
4348
<Parameter Name="value" Type="System.Void*" />
4449
</Parameters>
4550
<Docs>
46-
<param name="value">To be added.</param>
47-
<summary>To be added.</summary>
51+
<param name="value">The pointer value representing the self context.</param>
52+
<summary>Creates a new instance of the SwiftSelf struct with the specified pointer value.</summary>
4853
<remarks>To be added.</remarks>
4954
</Docs>
5055
</Member>
@@ -63,7 +68,7 @@
6368
<ReturnType>System.Void*</ReturnType>
6469
</ReturnValue>
6570
<Docs>
66-
<summary>To be added.</summary>
71+
<summary>Gets the pointer of the self context.</summary>
6772
<value>To be added.</value>
6873
<remarks>To be added.</remarks>
6974
</Docs>

‎xml/System.Runtime.InteropServices.Swift/SwiftSelf`1.xml

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,13 @@
3636
</Attributes>
3737
<Docs>
3838
<typeparam name="T">To be added.</typeparam>
39-
<summary>To be added.</summary>
40-
<remarks>To be added.</remarks>
39+
<summary>Represents the Swift 'self' context when the argument is Swift frozen struct T, which is either enregistered into multiple registers, or passed by reference in the 'self' register.</summary>
40+
<remarks>
41+
<para> This struct is used to pass the Swift frozen struct T to Swift functions in the context of interop with .NET.
42+
</para>
43+
<para> Here's an example of how a SwiftSelf&lt;T&gt; context can be declared:
44+
<code lang="csharp"> [UnmanagedCallConv(CallConvs = [typeof(CallConvSwift)])] [LibraryImport("SwiftLibrary", EntryPoint = "export")] public static extern void swiftFunction(SwiftSelf&lt;T&gt; self); </code></para>
45+
</remarks>
4146
</Docs>
4247
<Members>
4348
<Member MemberName=".ctor">
@@ -56,8 +61,8 @@
5661
<Parameter Name="value" Type="T" />
5762
</Parameters>
5863
<Docs>
59-
<param name="value">To be added.</param>
60-
<summary>To be added.</summary>
64+
<param name="value">The value representing the self context.</param>
65+
<summary>Creates a new instance of the SwiftSelf struct with the specified value.</summary>
6166
<remarks>To be added.</remarks>
6267
</Docs>
6368
</Member>
@@ -77,7 +82,7 @@
7782
<ReturnType>T</ReturnType>
7883
</ReturnValue>
7984
<Docs>
80-
<summary>To be added.</summary>
85+
<summary>Gets the value representing the Swift frozen struct.</summary>
8186
<value>To be added.</value>
8287
<remarks>To be added.</remarks>
8388
</Docs>

‎xml/System.Runtime.InteropServices/Architecture.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -261,7 +261,7 @@
261261
</ReturnValue>
262262
<MemberValue>9</MemberValue>
263263
<Docs>
264-
<summary>To be added.</summary>
264+
<summary>A RiscV 64-bit processor architecture.</summary>
265265
</Docs>
266266
</Member>
267267
<Member MemberName="S390x">

0 commit comments

Comments
 (0)