Skip to content

Commit ef4744f

Browse files
carlossanlopRon Petrusha
carlossanlop
authored and
Ron Petrusha
committed
Automatically port Reflection.Metadata M-U APIs (#3202)
* Automatically port Reflection.Metadata M-U APIs * Update ManifestResource.xml * Update ManifestResourceHandleCollection.xml * Update MemberReferenceHandleCollection.xml * Update MetadataReader.xml * Update MetadataReaderProvider.xml * Update MetadataStreamOptions.xml * Update MetadataStringComparer.xml * Update MetadataStringDecoder.xml * Update MethodDebugInformation.xml * Update MethodDebugInformationHandle.xml * Update MethodDefinitionHandle.xml * Update NamespaceDefinitionHandle.xml * Update ParameterHandleCollection.xml * Update SignatureTypeCode.xml * Update TypeDefinitionHandleCollection.xml * Update TypeReferenceHandleCollection.xml * Update UserStringHandle.xml * Fixed bad cref * Correct code example comment
1 parent 870f983 commit ef4744f

21 files changed

+322
-47
lines changed

‎xml/System.Reflection.Metadata/ManifestResource.xml‎

Lines changed: 38 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,15 @@
5151
<Docs>
5252
<summary>Gets the manifest resource attributes.</summary>
5353
<value>A bitwise combination of the enumeration values that specify the manifest resource attributes.</value>
54-
<remarks>To be added.</remarks>
54+
<remarks>
55+
<format type="text/markdown"><![CDATA[
56+
57+
## Remarks
58+
59+
Corresponds to the `Flags` field of the `ManifestResource` table in the [ECMA-335 Standard](https://www.ecma-international.org/publications/standards/Ecma-335.htm).
60+
61+
]]></format>
62+
</remarks>
5563
</Docs>
5664
</Member>
5765
<Member MemberName="GetCustomAttributes">
@@ -106,7 +114,17 @@
106114
Gets the implementation entity handle.
107115
</summary>
108116
<value>An EntityHandle instance. If the <see cref="P:System.Reflection.Metadata.EntityHandle.IsNil" /> property is <see langword="true" />, the returned handle will have default values.</value>
109-
<remarks>To be added.</remarks>
117+
<remarks>
118+
<format type="text/markdown"><![CDATA[
119+
120+
## Remarks
121+
122+
Corresponds to the `Implementation` field of the `ManifestResource` table in the ECMA-335 Standard.
123+
124+
If `nil`, then <xref:System.Reflection.Metadata.ManifestResource.Offset> is an offset in the PE image that contains the metadata, starting from the Resource entry in the CLI header.
125+
126+
]]></format>
127+
</remarks>
110128
</Docs>
111129
</Member>
112130
<Member MemberName="Name">
@@ -132,7 +150,15 @@
132150
<Docs>
133151
<summary>Gets the resource name.</summary>
134152
<value>The resource name.</value>
135-
<remarks>To be added.</remarks>
153+
<remarks>
154+
<format type="text/markdown"><![CDATA[
155+
156+
## Remarks
157+
158+
Corresponds to the `Name` field of the `ManifestResource` table in the ECMA-335 Standard.
159+
160+
]]></format>
161+
</remarks>
136162
</Docs>
137163
</Member>
138164
<Member MemberName="Offset">
@@ -158,7 +184,15 @@
158184
<Docs>
159185
<summary>Gets the byte offset within the referenced file at which this resource record begins.</summary>
160186
<value>The byte offset within the referenced file at which this resource record begins.</value>
161-
<remarks>To be added.</remarks>
187+
<remarks>
188+
<format type="text/markdown"><![CDATA[
189+
190+
## Remarks
191+
192+
Corresponds to the `Offset` field of the `ManifestResource` table in the ECMA-335 Standard.
193+
194+
]]></format>
195+
</remarks>
162196
</Docs>
163197
</Member>
164198
</Members>

‎xml/System.Reflection.Metadata/ManifestResourceHandleCollection.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@
3737
</Attribute>
3838
</Attributes>
3939
<Docs>
40-
<summary>To be added.</summary>
40+
<summary>Represents a collection of <see cref="T:System.Reflection.Metadata.ManifestResourceHandle" /> instances.</summary>
4141
<remarks>To be added.</remarks>
4242
</Docs>
4343
<Members>

‎xml/System.Reflection.Metadata/MemberReferenceHandleCollection.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@
3737
</Attribute>
3838
</Attributes>
3939
<Docs>
40-
<summary>To be added.</summary>
40+
<summary>Represents a collection of <see cref="T:System.Reflection.Metadata.MemberReferenceHandle" /> instances.</summary>
4141
<remarks>To be added.</remarks>
4242
</Docs>
4343
<Members>

‎xml/System.Reflection.Metadata/MetadataReader.xml‎

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
</Base>
2020
<Interfaces />
2121
<Docs>
22-
<summary>To be added.</summary>
22+
<summary>Reads metadata as defined by the ECMA 335 CLI specification.</summary>
2323
<remarks>To be added.</remarks>
2424
</Docs>
2525
<Members>
@@ -44,10 +44,18 @@
4444
<Parameter Name="length" Type="System.Int32" />
4545
</Parameters>
4646
<Docs>
47-
<param name="metadata">To be added.</param>
48-
<param name="length">To be added.</param>
47+
<param name="metadata">A pointer to the first byte in a block of metadata.</param>
48+
<param name="length">The number of bytes in the block.</param>
4949
<summary>Initializes a new instance of the <see cref="T:System.Reflection.Metadata.MetadataReader" /> class from the metadata stored at the given memory location.</summary>
50-
<remarks>To be added.</remarks>
50+
<remarks>
51+
<format type="text/markdown"><![CDATA[
52+
53+
## Remarks
54+
55+
The memory is owned by the caller. It must be kept alive and unmodified throughout the lifetime of the <xref:System.Reflection.Metadata.MetadataReader>.
56+
57+
]]></format>
58+
</remarks>
5159
</Docs>
5260
</Member>
5361
<Member MemberName=".ctor">
@@ -76,7 +84,17 @@
7684
<param name="length">To be added.</param>
7785
<param name="options">To be added.</param>
7886
<summary>Initializes a new instance of the <see cref="T:System.Reflection.Metadata.MetadataReader" /> class from the metadata stored at the given memory location.</summary>
79-
<remarks>To be added.</remarks>
87+
<remarks>
88+
<format type="text/markdown"><![CDATA[
89+
90+
## Remarks
91+
92+
The memory is owned by the caller. It must be kept memory alive and unmodified throughout the lifetime of the <xref:System.Reflection.Metadata.MetadataReader>.
93+
94+
Use <xref:System.Reflection.Metadata.PEReaderExtensions.GetMetadataReader(System.Reflection.PortableExecutable.PEReader,System.Reflection.Metadata.MetadataReaderOptions)?displayProperty=nameWithType> to obtain metadata from a PE image.
95+
96+
]]></format>
97+
</remarks>
8098
</Docs>
8199
</Member>
82100
<Member MemberName=".ctor">
@@ -107,7 +125,17 @@
107125
<param name="options">To be added.</param>
108126
<param name="utf8Decoder">To be added.</param>
109127
<summary>Initializes a new instance of the <see cref="T:System.Reflection.Metadata.MetadataReader" /> class from the metadata stored at the given memory location.</summary>
110-
<remarks>To be added.</remarks>
128+
<remarks>
129+
<format type="text/markdown"><![CDATA[
130+
131+
## Remarks
132+
133+
The memory is owned by the caller. It must be kept memory alive and unmodified throughout the lifetime of the <xref:System.Reflection.Metadata.MetadataReader>.
134+
135+
Use <xref:System.Reflection.Metadata.PEReaderExtensions.GetMetadataReader(System.Reflection.PortableExecutable.PEReader,System.Reflection.Metadata.MetadataReaderOptions,System.Reflection.Metadata.MetadataStringDecoder)?displayProperty=nameWithType> to obtain metadata from a PE image.
136+
137+
]]></format>
138+
</remarks>
111139
<exception cref="T:System.ArgumentOutOfRangeException">
112140
<paramref name="length" /> is not positive.</exception>
113141
<exception cref="T:System.ArgumentNullException">

‎xml/System.Reflection.Metadata/MetadataReaderProvider.xml‎

Lines changed: 80 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,20 @@
2222
</Interface>
2323
</Interfaces>
2424
<Docs>
25-
<summary>To be added.</summary>
26-
<remarks>To be added.</remarks>
25+
<summary>Provides a <see cref="T:System.Reflection.Metadata.MetadataReader" /> for metadata stored in an array of bytes, a memory block, or a stream.</summary>
26+
<remarks>
27+
<format type="text/markdown"><![CDATA[
28+
29+
## Remarks
30+
31+
`MetadataReaderProvider` supports the following formats:
32+
33+
- ECMA-335 CLI (Common Language Infrastructure) metadata (<xref:System.Reflection.Metadata.MetadataReaderProvider.FromMetadataImage(System.Byte*,System.Int32)>).
34+
- Edit and Continue metadata delta (<xref:System.Reflection.Metadata.MetadataReaderProvider.FromMetadataImage(System.Byte*,System.Int32)>).
35+
- Portable PDB metadata (<xref:System.Reflection.Metadata.MetadataReaderProvider.FromPortablePdbImage(System.Byte*,System.Int32)>).
36+
37+
]]></format>
38+
</remarks>
2739
</Docs>
2840
<Members>
2941
<Member MemberName="Dispose">
@@ -51,7 +63,17 @@
5163
<Parameters />
5264
<Docs>
5365
<summary>Disposes all memory allocated by the reader.</summary>
54-
<remarks>To be added.</remarks>
66+
<remarks>
67+
<format type="text/markdown"><![CDATA[
68+
69+
## Remarks
70+
71+
<xref:System.Reflection.Metadata.MetadataReaderProvider.Dispose> can be called multiple times (but not in parallel).
72+
73+
It is not safe to call <xref:System.Reflection.Metadata.MetadataReaderProvider.Dispose> in parallel with any other operation on the <xref:System.Reflection.Metadata.MetadataReaderProvider> or when reading from the underlying memory.
74+
75+
]]></format>
76+
</remarks>
5577
</Docs>
5678
</Member>
5779
<Member MemberName="FromMetadataImage">
@@ -80,7 +102,15 @@
80102
<param name="image">Metadata image.</param>
81103
<summary>Creates a provider over a byte array.</summary>
82104
<returns>The new provider.</returns>
83-
<remarks>To be added.</remarks>
105+
<remarks>
106+
<format type="text/markdown"><![CDATA[
107+
108+
## Remarks
109+
110+
The content of the image is not read during the construction of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
111+
112+
]]></format>
113+
</remarks>
84114
<exception cref="T:System.ArgumentNullException">
85115
<paramref name="image" /> is <see langword="null" />.</exception>
86116
</Docs>
@@ -112,7 +142,19 @@
112142
<param name="size">The size of the metadata blob.</param>
113143
<summary>Creates a metadata provider over an image stored in memory.</summary>
114144
<returns>The new metadata provider.</returns>
115-
<remarks>To be added.</remarks>
145+
<remarks>
146+
<format type="text/markdown"><![CDATA[
147+
148+
## Remarks
149+
150+
The memory is owned by the caller and is not released on disposal of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
151+
152+
The caller is responsible for keeping the memory alive and unmodified throughout the lifetime of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
153+
154+
The content of the blob is not read during the construction of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
155+
156+
]]></format>
157+
</remarks>
116158
<exception cref="T:System.ArgumentNullException">
117159
<paramref name="start" /> is <see cref="F:System.IntPtr.Zero" />.</exception>
118160
<exception cref="T:System.ArgumentOutOfRangeException">
@@ -192,7 +234,15 @@ If <xref:System.Reflection.Metadata.MetadataStreamOptions.PrefetchMetadata?displ
192234
<param name="image">A portable PDB image.</param>
193235
<summary>Creates a portable PDB metadata provider over a byte array.</summary>
194236
<returns>The new portable PDB metadata provider .</returns>
195-
<remarks>To be added.</remarks>
237+
<remarks>
238+
<format type="text/markdown"><![CDATA[
239+
240+
## Remarks
241+
242+
The content of the image is not read during the construction of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
243+
244+
]]></format>
245+
</remarks>
196246
<exception cref="T:System.ArgumentNullException">
197247
<paramref name="image" /> is <see langword="null" />.</exception>
198248
</Docs>
@@ -224,7 +274,19 @@ If <xref:System.Reflection.Metadata.MetadataStreamOptions.PrefetchMetadata?displ
224274
<param name="size">The size of the portable PDB blob.</param>
225275
<summary>Creates a portable PDB metadata provider over a blob stored in memory.</summary>
226276
<returns>The new portable PDB metadata provider.</returns>
227-
<remarks>To be added.</remarks>
277+
<remarks>
278+
<format type="text/markdown"><![CDATA[
279+
280+
## Remarks
281+
282+
The memory is owned by the caller and not released on disposal of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
283+
284+
The caller is responsible for keeping the memory alive and unmodified throughout the lifetime of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
285+
286+
The content of the blob is not read during the construction of the <xref:System.Reflection.Metadata.MetadataReaderProvider>.
287+
288+
]]></format>
289+
</remarks>
228290
<exception cref="T:System.ArgumentNullException">
229291
<paramref name="start" /> is <see cref="F:System.IntPtr.Zero" />.</exception>
230292
<exception cref="T:System.ArgumentOutOfRangeException">
@@ -306,7 +368,17 @@ If <xref:System.Reflection.Metadata.MetadataStreamOptions.PrefetchMetadata?displ
306368
<param name="utf8Decoder">The encoding to use.</param>
307369
<summary>Gets a <see cref="T:System.Reflection.Metadata.MetadataReader" /> from a <see cref="T:System.Reflection.Metadata.MetadataReaderProvider" />.</summary>
308370
<returns>A <see cref="T:System.Reflection.Metadata.MetadataReader" /> instance..</returns>
309-
<remarks>To be added.</remarks>
371+
<remarks>
372+
<format type="text/markdown"><![CDATA[
373+
374+
## Remarks
375+
376+
The caller must keep the <xref:System.Reflection.Metadata.MetadataReaderProvider> undisposed throughout the lifetime of the metadata reader.
377+
378+
If this method is called multiple times, each call with arguments equal to the arguments passed to the previous successful call returns the same instance of <xref:System.Reflection.Metadata.MetadataReader> as the previous call.
379+
380+
]]></format>
381+
</remarks>
310382
<exception cref="T:System.ArgumentException">The encoding of <paramref name="utf8Decoder" /> is not <see cref="T:System.Text.UTF8Encoding" />.</exception>
311383
<exception cref="T:System.PlatformNotSupportedException">The current platform is big-endian.</exception>
312384
<exception cref="T:System.IO.IOException">IO error while reading from the underlying stream.</exception>

‎xml/System.Reflection.Metadata/MetadataStreamOptions.xml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,8 @@
9595
</ReturnValue>
9696
<MemberValue>2</MemberValue>
9797
<Docs>
98-
<summary>Reads PDB metadata into memory right away.</summary>
98+
<summary><para>Reads PDB metadata into memory right away.</para><para>The underlying file may be closed and even deleted after the <see cref="T:System.Reflection.Metadata.MetadataReaderProvider" /> is constructed. <see cref="T:System.Reflection.Metadata.MetadataReaderProvider" /> closes the stream automatically by the time the constructor returns unless <see cref="F:System.Reflection.Metadata.MetadataStreamOptions.LeaveOpen" /> is specified.
99+
</para></summary>
99100
</Docs>
100101
</Member>
101102
</Members>

‎xml/System.Reflection.Metadata/MetadataStringComparer.xml‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,38 @@
2424
</Attribute>
2525
</Attributes>
2626
<Docs>
27-
<summary>To be added.</summary>
28-
<remarks>To be added.</remarks>
27+
<summary>Provides string comparison helpers to query strings in metadata while avoiding allocation if possible.</summary>
28+
<remarks>
29+
<format type="text/markdown"><![CDATA[
30+
31+
## Remarks
32+
33+
No allocation is performed unless both the handle argument and the value argument contain non-ASCII text.
34+
35+
Obtain instances using <xref:System.Reflection.Metadata.MetadataReader.StringComparer>. A default-initialized instance is useless and behaves as a `null` reference.
36+
37+
The code is optimized so that there is no additional overhead in re-obtaining a comparer over assigning it to a local. That is to say that a construct like:
38+
39+
```cs
40+
if (reader.StringComparer.Equals(typeDef.Namespace, "System") && reader.StringComparer.Equals(typeDef.Name, "Object")
41+
{
42+
/* found System.Object */
43+
}
44+
```
45+
is no less efficient than:
46+
47+
```cs
48+
var comparer = reader.StringComparer;
49+
if (comparer.Equals(typeDef.Namespace, "System") && comparer.Equals(typeDef.Name, "Object")
50+
{
51+
/* found System.Object */
52+
}
53+
```
54+
55+
The choice between them is therefore one of style and not performance.
56+
57+
]]></format>
58+
</remarks>
2959
</Docs>
3060
<Members>
3161
<Member MemberName="Equals">

‎xml/System.Reflection.Metadata/MetadataStringDecoder.xml‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,20 @@
1919
</Base>
2020
<Interfaces />
2121
<Docs>
22-
<summary>To be added.</summary>
23-
<remarks>To be added.</remarks>
22+
<summary>Provides the <see cref="T:System.Reflection.Metadata.MetadataReader" /> with a custom mechanism for decoding byte sequences in metadata that represent text.</summary>
23+
<remarks>
24+
<format type="text/markdown"><![CDATA[
25+
26+
## Remarks
27+
28+
This type can be used as follows:
29+
30+
1. To customize the treatment of invalid input. When no decoder is provided, the <xref:System.Reflection.Metadata.MetadataReader> uses the default fallback replacement with `\uFFFD`.
31+
32+
2. To reuse existing strings instead of allocating a new one for each decoding operation.
33+
34+
]]></format>
35+
</remarks>
2436
</Docs>
2537
<Members>
2638
<Member MemberName=".ctor">
@@ -45,7 +57,15 @@
4557
<Docs>
4658
<param name="encoding">The encoding to use.</param>
4759
<summary>Initializes a new instance of the <see cref="T:System.Reflection.Metadata.MetadataStringDecoder" /> class using the given encoding.</summary>
48-
<remarks>To be added.</remarks>
60+
<remarks>
61+
<format type="text/markdown"><![CDATA[
62+
63+
## Remarks
64+
65+
To cache and reuse existing strings, create a derived class and override <xref:System.Reflection.Metadata.MetadataStringDecoder.GetString(System.Byte*,System.Int32)>.
66+
67+
]]></format>
68+
</remarks>
4969
</Docs>
5070
</Member>
5171
<Member MemberName="DefaultUTF8">

0 commit comments

Comments
 (0)