Skip to content

Commit 3948c7f

Browse files
carlossanlopcarlossanlop
authored
Automatically port Reflection.Metadata.Ecma335 L-Metadata APIs (#3212)
* Automatically port Reflection.Metadata.Ecma335 L-Metadata APIs * Address suggestions * Rephrase * suggestions by Thraka * suggestion by Thraka
1 parent c34cb7c commit 3948c7f

File tree

7 files changed

+124
-99
lines changed

7 files changed

+124
-99
lines changed

‎xml/System.Reflection.Metadata.Ecma335/LabelHandle.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,7 @@
133133
<ReturnType>System.Int32</ReturnType>
134134
</ReturnValue>
135135
<Docs>
136-
<summary>To be added.</summary>
136+
<summary>1-based id identifying the label within the context of a <see cref="T:System.Reflection.Metadata.Ecma335.ControlFlowBuilder" />.</summary>
137137
<value>To be added.</value>
138138
<remarks>To be added.</remarks>
139139
</Docs>

‎xml/System.Reflection.Metadata.Ecma335/LiteralEncoder.xml

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
</Attribute>
2323
</Attributes>
2424
<Docs>
25-
<summary>To be added.</summary>
25+
<summary>Provides methods for encoding literals.</summary>
2626
<remarks>To be added.</remarks>
2727
</Docs>
2828
<Members>
@@ -45,7 +45,7 @@
4545
<Parameter Name="builder" Type="System.Reflection.Metadata.BlobBuilder" Index="0" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
4646
</Parameters>
4747
<Docs>
48-
<param name="builder">To be added.</param>
48+
<param name="builder">Creates a new instance of the <see cref="T:System.Reflection.Metadata.Ecma335.LiteralEncoder" /> class with the specified blob builder.</param>
4949
<summary>To be added.</summary>
5050
<remarks>To be added.</remarks>
5151
</Docs>
@@ -94,8 +94,8 @@
9494
</ReturnValue>
9595
<Parameters />
9696
<Docs>
97-
<summary>To be added.</summary>
98-
<returns>To be added.</returns>
97+
<summary>Returns the encoder used to encode the literal value.</summary>
98+
<returns>The encoder of the literal value.</returns>
9999
<remarks>To be added.</remarks>
100100
</Docs>
101101
</Member>
@@ -122,9 +122,9 @@
122122
<Parameter Name="scalar" Type="System.Action&lt;System.Reflection.Metadata.Ecma335.ScalarEncoder&gt;" Index="1" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
123123
</Parameters>
124124
<Docs>
125-
<param name="type">To be added.</param>
126-
<param name="scalar">To be added.</param>
127-
<summary>To be added.</summary>
125+
<param name="type">A delegate used to encode the type of the literal. Called first by this method.</param>
126+
<param name="scalar">A delegate used to encode the value of the literal. Called second by this method.</param>
127+
<summary>Encodes the type and the value of a literal using the specified delegates.</summary>
128128
<remarks>To be added.</remarks>
129129
</Docs>
130130
</Member>
@@ -151,9 +151,9 @@
151151
<Parameter Name="scalar" Type="System.Reflection.Metadata.Ecma335.ScalarEncoder" RefType="out" Index="1" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
152152
</Parameters>
153153
<Docs>
154-
<param name="type">To be added.</param>
155-
<param name="scalar">To be added.</param>
156-
<summary>To be added.</summary>
154+
<param name="type">When this method returns, a custom attribute element type encoder used to encode the type of the literal.</param>
155+
<param name="scalar">When this method returns, a scalar encoded used to encode the value of the literal.</param>
156+
<summary>Returns a pair of encoders that must be used to encode the type and value of a literal in the order they appear in the parameter list.</summary>
157157
<remarks>To be added.</remarks>
158158
</Docs>
159159
</Member>
@@ -180,9 +180,9 @@
180180
<Parameter Name="vector" Type="System.Action&lt;System.Reflection.Metadata.Ecma335.VectorEncoder&gt;" Index="1" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
181181
</Parameters>
182182
<Docs>
183-
<param name="arrayType">To be added.</param>
184-
<param name="vector">To be added.</param>
185-
<summary>To be added.</summary>
183+
<param name="arrayType">A delegate used to encode the type of the vector. Called first by this method.</param>
184+
<param name="vector">A delegate used to encode the items of the vector. Called second by this method.</param>
185+
<summary>Encodes the type and the items of a vector literal using the specified delegates.</summary>
186186
<remarks>To be added.</remarks>
187187
</Docs>
188188
</Member>
@@ -209,9 +209,9 @@
209209
<Parameter Name="vector" Type="System.Reflection.Metadata.Ecma335.VectorEncoder" RefType="out" Index="1" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0" />
210210
</Parameters>
211211
<Docs>
212-
<param name="arrayType">To be added.</param>
213-
<param name="vector">To be added.</param>
214-
<summary>To be added.</summary>
212+
<param name="arrayType">When this method returns, a custom attribute array type encoder used to encode the type of the vector.</param>
213+
<param name="vector">When this method returns, a vector encoder used to encode the items of the vector.</param>
214+
<summary>Returns a pair of encoders that must be used to encode the type and the items of a vector literal in the order they appear in the parameter list.</summary>
215215
<remarks>To be added.</remarks>
216216
</Docs>
217217
</Member>
@@ -235,8 +235,8 @@
235235
</ReturnValue>
236236
<Parameters />
237237
<Docs>
238-
<summary>To be added.</summary>
239-
<returns>To be added.</returns>
238+
<summary>Gets a vector encoder used to encode the items of a vector.</summary>
239+
<returns>A vector encoder used to encode the items of a vector.</returns>
240240
<remarks>To be added.</remarks>
241241
</Docs>
242242
</Member>

‎xml/System.Reflection.Metadata.Ecma335/MetadataAggregator.xml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -105,10 +105,10 @@
105105
<Parameter Name="generation" Type="System.Int32" RefType="out" />
106106
</Parameters>
107107
<Docs>
108-
<param name="handle">To be added.</param>
109-
<param name="generation">To be added.</param>
110-
<summary>To be added.</summary>
111-
<returns>To be added.</returns>
108+
<param name="handle">Handle of an entity in an aggregate metadata.</param>
109+
<param name="generation">The generation the entity is defined in.</param>
110+
<summary>Calculates the handle of the entity within the metadata generation it is defined in, given a handle of an entity in an aggregate metadata.</summary>
111+
<returns>Handle of the entity within the metadata <paramref name="generation" />.</returns>
112112
<remarks>To be added.</remarks>
113113
</Docs>
114114
</Member>

‎xml/System.Reflection.Metadata.Ecma335/MetadataReaderExtensions.xml

Lines changed: 16 additions & 16 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>Provides extension methods for working with certain raw elements of the ECMA-335 metadata tables and heaps.</summary>
2323
<remarks>To be added.</remarks>
2424
</Docs>
2525
<Members>
@@ -57,7 +57,7 @@
5757
</Parameters>
5858
<Docs>
5959
<param name="reader">To be added.</param>
60-
<summary>To be added.</summary>
60+
<summary>Enumerates entries of EnC log.</summary>
6161
<returns>To be added.</returns>
6262
<remarks>To be added.</remarks>
6363
</Docs>
@@ -96,7 +96,7 @@
9696
</Parameters>
9797
<Docs>
9898
<param name="reader">To be added.</param>
99-
<summary>To be added.</summary>
99+
<summary>Enumerates entries of EnC map.</summary>
100100
<returns>To be added.</returns>
101101
<remarks>To be added.</remarks>
102102
</Docs>
@@ -127,7 +127,7 @@
127127
<Docs>
128128
<param name="reader">To be added.</param>
129129
<param name="heapIndex">To be added.</param>
130-
<summary>To be added.</summary>
130+
<summary>Returns the offset from the start of metadata to the specified heap.</summary>
131131
<returns>To be added.</returns>
132132
<remarks>To be added.</remarks>
133133
</Docs>
@@ -158,7 +158,7 @@
158158
<Docs>
159159
<param name="reader">To be added.</param>
160160
<param name="heapIndex">To be added.</param>
161-
<summary>To be added.</summary>
161+
<summary>Returns the size of the specified heap.</summary>
162162
<returns>To be added.</returns>
163163
<remarks>To be added.</remarks>
164164
</Docs>
@@ -190,7 +190,7 @@
190190
<Docs>
191191
<param name="reader">To be added.</param>
192192
<param name="handle">To be added.</param>
193-
<summary>To be added.</summary>
193+
<summary>Returns the handle to the <see cref="T:System.Reflection.Metadata.Blob" /> that follows the given one in the <see cref="T:System.Reflection.Metadata.Blob" /> heap or a nil handle if it is the last one.</summary>
194194
<returns>To be added.</returns>
195195
<remarks>To be added.</remarks>
196196
</Docs>
@@ -222,7 +222,7 @@
222222
<Docs>
223223
<param name="reader">To be added.</param>
224224
<param name="handle">To be added.</param>
225-
<summary>To be added.</summary>
225+
<summary>Returns the a handle to the string that follows the given one in the string heap, or a nil handle if it is the last one.</summary>
226226
<returns>To be added.</returns>
227227
<remarks>To be added.</remarks>
228228
</Docs>
@@ -254,7 +254,7 @@
254254
<Docs>
255255
<param name="reader">To be added.</param>
256256
<param name="handle">To be added.</param>
257-
<summary>To be added.</summary>
257+
<summary>Returns the a handle to the UserString that follows the given one in the UserString heap or a nil handle if it is the last one.</summary>
258258
<returns>To be added.</returns>
259259
<remarks>To be added.</remarks>
260260
</Docs>
@@ -285,7 +285,7 @@
285285
<Docs>
286286
<param name="reader">To be added.</param>
287287
<param name="tableIndex">To be added.</param>
288-
<summary>To be added.</summary>
288+
<summary>Returns the offset from the start of metadata to the specified table.</summary>
289289
<returns>To be added.</returns>
290290
<remarks>To be added.</remarks>
291291
</Docs>
@@ -316,7 +316,7 @@
316316
<Docs>
317317
<param name="reader">To be added.</param>
318318
<param name="tableIndex">To be added.</param>
319-
<summary>To be added.</summary>
319+
<summary>Returns the number of rows in the specified table.</summary>
320320
<returns>To be added.</returns>
321321
<remarks>To be added.</remarks>
322322
</Docs>
@@ -347,7 +347,7 @@
347347
<Docs>
348348
<param name="reader">To be added.</param>
349349
<param name="tableIndex">To be added.</param>
350-
<summary>To be added.</summary>
350+
<summary>Returns the size of a row in the specified table.</summary>
351351
<returns>To be added.</returns>
352352
<remarks>To be added.</remarks>
353353
</Docs>
@@ -386,8 +386,8 @@
386386
</Parameters>
387387
<Docs>
388388
<param name="reader">To be added.</param>
389-
<summary>To be added.</summary>
390-
<returns>To be added.</returns>
389+
<summary>Enumerate types that define one or more events.</summary>
390+
<returns>The resulting sequence corresponds exactly to entries in EventMap table, i.e. n-th returned <see cref="T:System.Reflection.Metadata.TypeDefinitionHandle" /> is stored in n-th row of EventMap.</returns>
391391
<remarks>To be added.</remarks>
392392
</Docs>
393393
</Member>
@@ -425,8 +425,8 @@
425425
</Parameters>
426426
<Docs>
427427
<param name="reader">To be added.</param>
428-
<summary>To be added.</summary>
429-
<returns>To be added.</returns>
428+
<summary>Enumerate types that define one or more properties.</summary>
429+
<returns>The resulting sequence corresponds exactly to entries in the property map table, that is, the n-th returned <see cref="T:System.Reflection.Metadata.TypeDefinitionHandle" /> is stored in n-th row of the property map.</returns>
430430
<remarks>To be added.</remarks>
431431
</Docs>
432432
</Member>
@@ -457,7 +457,7 @@
457457
<param name="reader">To be added.</param>
458458
<param name="typeHandle">To be added.</param>
459459
<param name="rawTypeKind">To be added.</param>
460-
<summary>To be added.</summary>
460+
<summary>Given a type handle and a raw type kind found in a signature blob determines whether the target type is a value type or a reference type.</summary>
461461
<returns>To be added.</returns>
462462
<remarks>To be added.</remarks>
463463
</Docs>

‎xml/System.Reflection.Metadata.Ecma335/MetadataRootBuilder.xml

Lines changed: 32 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,16 @@
1717
</Base>
1818
<Interfaces />
1919
<Docs>
20-
<summary>To be added.</summary>
21-
<remarks>To be added.</remarks>
20+
<summary>Builder of a Metadata Root to be embedded in a Portable Executable image.</summary>
21+
<remarks>
22+
<format type="text/markdown"><![CDATA[
23+
24+
## Remarks
25+
26+
Metadata root constitutes of a metadata header followed by metadata streams (`#~`, `#Strings`, `#US`, `#Guid` and `#Blob`).
27+
28+
]]></format>
29+
</remarks>
2230
</Docs>
2331
<Members>
2432
<Member MemberName=".ctor">
@@ -41,11 +49,19 @@
4149
<Parameter Name="suppressValidation" Type="System.Boolean" />
4250
</Parameters>
4351
<Docs>
44-
<param name="tablesAndHeaps">To be added.</param>
45-
<param name="metadataVersion">To be added.</param>
46-
<param name="suppressValidation">To be added.</param>
47-
<summary>To be added.</summary>
48-
<remarks>To be added.</remarks>
52+
<param name="tablesAndHeaps">Builder populated with metadata entities stored in tables and values stored in heaps. The entities and values will be enumerated when serializing the metadata root.</param>
53+
<param name="metadataVersion">The version string written to the metadata header. The default value is "v4.0.30319".</param>
54+
<param name="suppressValidation"><see langword="true" /> to suppress basic validation of metadata tables during serialization; otherwise, <paramref name="false" />.</param>
55+
<summary>Creates a builder of a metadata root.</summary>
56+
<remarks>
57+
<format type="text/markdown"><![CDATA[
58+
59+
## Remarks
60+
61+
When `suppressValidation` is set to `true`, the validation verifies that entries in the tables were added in order required by the ECMA specification. It does not enforce all specification requirements on metadata tables.
62+
63+
]]></format>
64+
</remarks>
4965
</Docs>
5066
</Member>
5167
<Member MemberName="MetadataVersion">
@@ -67,8 +83,8 @@
6783
<ReturnType>System.String</ReturnType>
6884
</ReturnValue>
6985
<Docs>
70-
<summary>To be added.</summary>
71-
<value>To be added.</value>
86+
<summary>The metadata version.</summary>
87+
<value>A string that represents the metadata version.</value>
7288
<remarks>To be added.</remarks>
7389
</Docs>
7490
</Member>
@@ -96,10 +112,10 @@
96112
<Parameter Name="mappedFieldDataStreamRva" Type="System.Int32" />
97113
</Parameters>
98114
<Docs>
99-
<param name="builder">To be added.</param>
100-
<param name="methodBodyStreamRva">To be added.</param>
101-
<param name="mappedFieldDataStreamRva">To be added.</param>
102-
<summary>To be added.</summary>
115+
<param name="builder">Builder to write to.</param>
116+
<param name="methodBodyStreamRva">The relative virtual address of the start of the method body stream. Used to calculate the final value of RVA fields of MethodDef table.</param>
117+
<param name="mappedFieldDataStreamRva">The relative virtual address of the start of the field init data stream. Used to calculate the final value of RVA fields of FieldRVA table.</param>
118+
<summary>Serializes metadata root content into the given <see cref="T:System.Reflection.Metadata.BlobBuilder" />.</summary>
103119
<remarks>To be added.</remarks>
104120
</Docs>
105121
</Member>
@@ -122,7 +138,7 @@
122138
<ReturnType>System.Reflection.Metadata.Ecma335.MetadataSizes</ReturnType>
123139
</ReturnValue>
124140
<Docs>
125-
<summary>To be added.</summary>
141+
<summary>Returns sizes of various metadata structures.</summary>
126142
<value>To be added.</value>
127143
<remarks>To be added.</remarks>
128144
</Docs>
@@ -146,8 +162,8 @@
146162
<ReturnType>System.Boolean</ReturnType>
147163
</ReturnValue>
148164
<Docs>
149-
<summary>To be added.</summary>
150-
<value>To be added.</value>
165+
<summary>Determines if basic validation of metadata tables should be suppressed. The validation verifies that entries in the tables were added in order required by the ECMA specification. It does not enforce all specification requirements on metadata tables.</summary>
166+
<value><see langword="true" /> to suppress basic validation of metadata tables; otherwise, <see langword="false" />.</value>
151167
<remarks>To be added.</remarks>
152168
</Docs>
153169
</Member>

‎xml/System.Reflection.Metadata.Ecma335/MetadataSizes.xml

Lines changed: 14 additions & 6 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 information on sizes of various metadata structures.</summary>
2121
<remarks>To be added.</remarks>
2222
</Docs>
2323
<Members>
@@ -40,7 +40,7 @@
4040
<ReturnType>System.Collections.Immutable.ImmutableArray&lt;System.Int32&gt;</ReturnType>
4141
</ReturnValue>
4242
<Docs>
43-
<summary>To be added.</summary>
43+
<summary>External table row count.</summary>
4444
<value>To be added.</value>
4545
<remarks>To be added.</remarks>
4646
</Docs>
@@ -68,7 +68,7 @@
6868
</Parameters>
6969
<Docs>
7070
<param name="index">To be added.</param>
71-
<summary>To be added.</summary>
71+
<summary>Returns aligned size of the specified heap.</summary>
7272
<returns>To be added.</returns>
7373
<remarks>To be added.</remarks>
7474
</Docs>
@@ -92,9 +92,17 @@
9292
<ReturnType>System.Collections.Immutable.ImmutableArray&lt;System.Int32&gt;</ReturnType>
9393
</ReturnValue>
9494
<Docs>
95-
<summary>To be added.</summary>
95+
<summary>Exact (unaligned) heap sizes.</summary>
9696
<value>To be added.</value>
97-
<remarks>To be added.</remarks>
97+
<remarks>
98+
<format type="text/markdown"><![CDATA[
99+
100+
## Remarks
101+
102+
Use <xref:System.Reflection.Metadata.Ecma335.MetadataSizes.GetAlignedHeapSize(System.Reflection.Metadata.Ecma335.HeapIndex)> to get an aligned heap size.
103+
104+
]]></format>
105+
</remarks>
98106
</Docs>
99107
</Member>
100108
<Member MemberName="RowCounts">
@@ -116,7 +124,7 @@
116124
<ReturnType>System.Collections.Immutable.ImmutableArray&lt;System.Int32&gt;</ReturnType>
117125
</ReturnValue>
118126
<Docs>
119-
<summary>To be added.</summary>
127+
<summary>Table row counts.</summary>
120128
<value>To be added.</value>
121129
<remarks>To be added.</remarks>
122130
</Docs>

0 commit comments

Comments
 (0)