Skip to content

Commit f150e32

Browse files
carlossanlopRon Petrusha
carlossanlop
and
Ron Petrusha
committed
Port System.Reflection.Metadata source code comments to Docs (Method*-T files) (#2335)
* Port System.Reflection.Metadata source code comments to Docs (Method*-T files) * Proper language for a *Handle structs with default value. * Apply suggestions from code review Suggestions by rpetrusha Co-Authored-By: Ron Petrusha <[email protected]>
1 parent 5fa526e commit f150e32

11 files changed

+120
-87
lines changed

‎xml/System.Reflection.Metadata/MethodBodyBlock.xml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -259,10 +259,10 @@
259259
<ReturnType>System.Int32</ReturnType>
260260
</ReturnValue>
261261
<Docs>
262-
<summary>To be added.</summary>
263-
<value>To be added.</value>
262+
<summary>Gets the size of the method body, including the header, IL, and exception regions.</summary>
263+
<value>The size of the method body.</value>
264264
<remarks>To be added.</remarks>
265265
</Docs>
266266
</Member>
267267
</Members>
268-
</Type>
268+
</Type>

‎xml/System.Reflection.Metadata/MethodDebugInformation.xml

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,8 @@
4747
<ReturnType>System.Reflection.Metadata.DocumentHandle</ReturnType>
4848
</ReturnValue>
4949
<Docs>
50-
<summary>To be added.</summary>
51-
<value>To be added.</value>
50+
<summary>Gets the handle of the single document containing all sequence points of the method. </summary>
51+
<value>The handle of the single document containing all sequence points of the method, or a handle whose <see cref="P:System.Reflection.Metadata.DocumentHandle.IsNil" /> property is <see langword="true" /> if the method doesn't have sequence points or spans multiple documents. </value>
5252
<remarks>To be added.</remarks>
5353
</Docs>
5454
</Member>
@@ -73,8 +73,8 @@
7373
</ReturnValue>
7474
<Parameters />
7575
<Docs>
76-
<summary>To be added.</summary>
77-
<returns>To be added.</returns>
76+
<summary>Returns a collection of sequence points decoded from <see cref="P:System.Reflection.Metadata.MethodDebugInformation.SequencePointsBlob" />.</summary>
77+
<returns>A collection of sequence points.</returns>
7878
<remarks>To be added.</remarks>
7979
</Docs>
8080
</Member>
@@ -99,8 +99,8 @@
9999
</ReturnValue>
100100
<Parameters />
101101
<Docs>
102-
<summary>To be added.</summary>
103-
<returns>To be added.</returns>
102+
<summary>Returns the kickoff method of the state machine.</summary>
103+
<returns>The kickoff method of the state machine, if the method is a <c>MoveNext</c> method of a state machine. Otherwise, it returns a handle whose <see cref="P:System.Reflection.Metadata.MethodDefinitionHandle.IsNil" /> property is <see langword="true" />..</returns>
104104
<remarks>To be added.</remarks>
105105
</Docs>
106106
</Member>
@@ -124,8 +124,8 @@
124124
<ReturnType>System.Reflection.Metadata.StandaloneSignatureHandle</ReturnType>
125125
</ReturnValue>
126126
<Docs>
127-
<summary>To be added.</summary>
128-
<value>To be added.</value>
127+
<summary>Returns a local signature handle. </summary>
128+
<value>A local signature handle, or a handle whose <see cref="P:System.Reflection.Metadata.StandaloneSignatureHandle.IsNil" /> property is <see langword="true" /> if the method doesn't define any local variables.</value>
129129
<remarks>To be added.</remarks>
130130
</Docs>
131131
</Member>
@@ -149,10 +149,17 @@
149149
<ReturnType>System.Reflection.Metadata.BlobHandle</ReturnType>
150150
</ReturnValue>
151151
<Docs>
152-
<summary>To be added.</summary>
153-
<value>To be added.</value>
154-
<remarks>To be added.</remarks>
152+
<summary>Returns a blob encoding sequence points.
153+
</summary>
154+
<value>A blob encoding sequence points, or a handle whose <see cref="P:System.Reflection.Metadata.BlobHandle.IsNil" /> property is <see langword="true" /> if the method doesn't have sequence points.</value>
155+
<remarks>
156+
<format type="text/markdown"><![CDATA[
157+
158+
Use the <see cref="M:System.Reflection.Metadata.MethodDebugInformation.GetSequencePoints" /> method to decode the blob.
159+
160+
]]></format>
161+
</remarks>
155162
</Docs>
156163
</Member>
157164
</Members>
158-
</Type>
165+
</Type>

‎xml/System.Reflection.Metadata/MethodDebugInformationHandle.xml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -340,10 +340,10 @@
340340
</ReturnValue>
341341
<Parameters />
342342
<Docs>
343-
<summary>To be added.</summary>
344-
<returns>To be added.</returns>
343+
<summary>Returns a handle to <see cref="T:System.Reflection.Metadata.MethodDefinition" /> corresponding to this handle.</summary>
344+
<returns>A method definition handle that corresponds to this handle.</returns>
345345
<remarks>To be added.</remarks>
346346
</Docs>
347347
</Member>
348348
</Members>
349-
</Type>
349+
</Type>

‎xml/System.Reflection.Metadata/MethodDefinitionHandle.xml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -351,10 +351,10 @@
351351
</ReturnValue>
352352
<Parameters />
353353
<Docs>
354-
<summary>To be added.</summary>
355-
<returns>To be added.</returns>
354+
<summary>Returns a handle to a <see cref="T:System.Reflection.Metadata.MethodDebugInformation" /> corresponding to this handle.</summary>
355+
<returns>A method debug information handle that corresponds to this handle.</returns>
356356
<remarks>To be added.</remarks>
357357
</Docs>
358358
</Member>
359359
</Members>
360-
</Type>
360+
</Type>

‎xml/System.Reflection.Metadata/MethodSpecification.xml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -140,8 +140,8 @@
140140
<ReturnType>System.Reflection.Metadata.EntityHandle</ReturnType>
141141
</ReturnValue>
142142
<Docs>
143-
<summary>To be added.</summary>
144-
<value>To be added.</value>
143+
<summary>Gets a <see langword="MethodDef" /> or <see langword="MemberRef" /> handle specifying which generic method this instance refers to (that is, which generic method it is an instantiation of).</summary>
144+
<value>A <see langword="MethodDef" /> or <see langword="MemberRef" /> handle specifying which generic method this instance refers to.</value>
145145
<remarks>To be added.</remarks>
146146
</Docs>
147147
</Member>
@@ -166,10 +166,10 @@
166166
<ReturnType>System.Reflection.Metadata.BlobHandle</ReturnType>
167167
</ReturnValue>
168168
<Docs>
169-
<summary>To be added.</summary>
170-
<value>To be added.</value>
169+
<summary>Gets a handle to the signature blob.</summary>
170+
<value>A handle to the signature blob.</value>
171171
<remarks>To be added.</remarks>
172172
</Docs>
173173
</Member>
174174
</Members>
175-
</Type>
175+
</Type>

‎xml/System.Reflection.Metadata/NamespaceDefinition.xml

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,8 @@
4444
<ReturnType>System.Collections.Immutable.ImmutableArray&lt;System.Reflection.Metadata.ExportedTypeHandle&gt;</ReturnType>
4545
</ReturnValue>
4646
<Docs>
47-
<summary>To be added.</summary>
48-
<value>To be added.</value>
47+
<summary>Gets all exported types that reside directly in a namespace.</summary>
48+
<value>An immutable array of exported type handles.</value>
4949
<remarks>To be added.</remarks>
5050
</Docs>
5151
</Member>
@@ -70,8 +70,8 @@
7070
<ReturnType>System.Reflection.Metadata.StringHandle</ReturnType>
7171
</ReturnValue>
7272
<Docs>
73-
<summary>To be added.</summary>
74-
<value>To be added.</value>
73+
<summary>Gets the unqualified name of the namespace definition.</summary>
74+
<value>The unqualified name of the namespace definition.</value>
7575
<remarks>To be added.</remarks>
7676
</Docs>
7777
</Member>
@@ -96,9 +96,20 @@
9696
<ReturnType>System.Collections.Immutable.ImmutableArray&lt;System.Reflection.Metadata.NamespaceDefinitionHandle&gt;</ReturnType>
9797
</ReturnValue>
9898
<Docs>
99-
<summary>To be added.</summary>
100-
<value>To be added.</value>
101-
<remarks>To be added.</remarks>
99+
<summary>Gets the namespace definitions that are direct children of the current namespace definition.</summary>
100+
<value>An immutable array of namespace definitions that are direct children of the current namespace definition.</value>
101+
<remarks>
102+
<format type="text/markdown">
103+
<![CDATA[
104+
## Remarks
105+
106+
For example:
107+
108+
* System.Collections and System.Linq are direct children of System.
109+
* System.Collections.Generic is a direct child of System.Collections.
110+
* System.Collections.Generic is *not* a direct child of System.
111+
]]></format>
112+
</remarks>
102113
</Docs>
103114
</Member>
104115
<Member MemberName="Parent">
@@ -122,8 +133,8 @@
122133
<ReturnType>System.Reflection.Metadata.NamespaceDefinitionHandle</ReturnType>
123134
</ReturnValue>
124135
<Docs>
125-
<summary>To be added.</summary>
126-
<value>To be added.</value>
136+
<summary>Gets the parent namespace.</summary>
137+
<value>The parent namespace.</value>
127138
<remarks>To be added.</remarks>
128139
</Docs>
129140
</Member>
@@ -148,10 +159,10 @@
148159
<ReturnType>System.Collections.Immutable.ImmutableArray&lt;System.Reflection.Metadata.TypeDefinitionHandle&gt;</ReturnType>
149160
</ReturnValue>
150161
<Docs>
151-
<summary>To be added.</summary>
152-
<value>To be added.</value>
162+
<summary>Gets all type definitions that reside directly in a namespace.</summary>
163+
<value>An immutable array of type definition handles.</value>
153164
<remarks>To be added.</remarks>
154165
</Docs>
155166
</Member>
156167
</Members>
157-
</Type>
168+
</Type>

‎xml/System.Reflection.Metadata/PEReaderExtensions.xml

Lines changed: 31 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,13 @@
5454
<Parameter Name="peReader" Type="System.Reflection.PortableExecutable.PEReader" RefType="this" />
5555
</Parameters>
5656
<Docs>
57-
<param name="peReader">To be added.</param>
58-
<summary>To be added.</summary>
59-
<returns>To be added.</returns>
57+
<param name="peReader">The current <see cref="T:System.Reflection.PortableExecutable.PEReader" /> instance.</param>
58+
<summary>Gets a <see cref="T:System.Reflection.Metadata.MetadataReader" /> from a <see cref="T:System.Reflection.PortableExecutable.PEReader" />.</summary>
59+
<returns>A metdata reader.</returns>
6060
<remarks>To be added.</remarks>
61+
<exception cref="T:System.ArgumentNullException"><paramref name="peReader" /> is <see langword="null" />.</exception>
62+
<exception cref="T:System.PlatformNotSupportedException">The current platform is big-endian.</exception>
63+
<exception cref="T:System.IO.IOException">IO error while reading from the underlying stream.</exception>
6164
</Docs>
6265
</Member>
6366
<Member MemberName="GetMetadataReader">
@@ -84,11 +87,14 @@
8487
<Parameter Name="options" Type="System.Reflection.Metadata.MetadataReaderOptions" />
8588
</Parameters>
8689
<Docs>
87-
<param name="peReader">To be added.</param>
88-
<param name="options">To be added.</param>
89-
<summary>To be added.</summary>
90-
<returns>To be added.</returns>
90+
<param name="peReader">The current <see cref="T:System.Reflection.PortableExecutable.PEReader" /> instance.</param>
91+
<param name="options">An enumeration value indicating the metadata reading configuration.</param>
92+
<summary>Gets a metadata reader with the specified metadata reading configuration from a <see cref="T:System.Reflection.PortableExecutable.PEReader" />.</summary>
93+
<returns>A metadata reader with the specified metadata reading configuration.</returns>
9194
<remarks>To be added.</remarks>
95+
<exception cref="T:System.ArgumentNullException"><paramref name="peReader" /> is <see langword="null" />.</exception>
96+
<exception cref="T:System.PlatformNotSupportedException">The current platform is big-endian.</exception>
97+
<exception cref="T:System.IO.IOException">IO error while reading from the underlying stream.</exception>
9298
</Docs>
9399
</Member>
94100
<Member MemberName="GetMetadataReader">
@@ -116,12 +122,16 @@
116122
<Parameter Name="utf8Decoder" Type="System.Reflection.Metadata.MetadataStringDecoder" />
117123
</Parameters>
118124
<Docs>
119-
<param name="peReader">To be added.</param>
120-
<param name="options">To be added.</param>
121-
<param name="utf8Decoder">To be added.</param>
122-
<summary>To be added.</summary>
123-
<returns>To be added.</returns>
125+
<param name="peReader">The current <see cref="T:System.Reflection.PortableExecutable.PEReader" /> instance.</param>
126+
<param name="options">An enumeration value indicating the metadata reading configuration.</param>
127+
<param name="utf8Decoder">A metadata string decoder with the encoding configuration.</param>
128+
<summary>Gets a metadata reader with the specified metadata reading configuration and encoding configuration from a <see cref="T:System.Reflection.PortableExecutable.PEReader" />.</summary>
129+
<returns>>A metadata reader with the specified metadata reading configuration and encoding configuration.</returns>
124130
<remarks>To be added.</remarks>
131+
<exception cref="T:System.ArgumentNullException"><paramref name="peReader" /> is <see langword="null" />.</exception>
132+
<exception cref="T:System.ArgumentException">The encoding of <paramref name="utf8Decoder" /> is not <see cref="T:System.Text.UTF8Encoding" />.</exception>
133+
<exception cref="T:System.PlatformNotSupportedException">The current platform is big-endian.</exception>
134+
<exception cref="T:System.IO.IOException">IO error while reading from the underlying stream.</exception>
125135
</Docs>
126136
</Member>
127137
<Member MemberName="GetMethodBody">
@@ -148,12 +158,16 @@
148158
<Parameter Name="relativeVirtualAddress" Type="System.Int32" />
149159
</Parameters>
150160
<Docs>
151-
<param name="peReader">To be added.</param>
152-
<param name="relativeVirtualAddress">To be added.</param>
153-
<summary>To be added.</summary>
154-
<returns>To be added.</returns>
161+
<param name="peReader">The current <see cref="T:System.Reflection.PortableExecutable.PEReader" /> instance.</param>
162+
<param name="relativeVirtualAddress">The Relative Virtual Address (RVA).</param>
163+
<summary>Returns a body block of a method with the specified Relative Virtual Address (RVA);</summary>
164+
<returns>A method block body instance.</returns>
155165
<remarks>To be added.</remarks>
166+
<exception cref="T:System.ArgumentNullException"><paramref name="peReader" /> is <see langword="null" />.</exception>
167+
<exception cref="T:System.BadImageFormatException">The body is not found in the metadata or is invalid.</exception>
168+
<exception cref="T:System.InvalidOperationException">The section where the method is stored is not available.</exception>
169+
<exception cref="T:System.IO.IOException">IO error occurred while reading from the underlying stream.</exception>
156170
</Docs>
157171
</Member>
158172
</Members>
159-
</Type>
173+
</Type>

‎xml/System.Reflection.Metadata/ReservedBlob`1.xml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -80,8 +80,8 @@
8080
</ReturnValue>
8181
<Parameters />
8282
<Docs>
83-
<summary>To be added.</summary>
84-
<returns>To be added.</returns>
83+
<summary>Returns a <see cref="T:System.Reflection.Metadata.BlobWriter" /> to be used to update the content.</summary>
84+
<returns>A blob writer to be used to update the content.</returns>
8585
<remarks>To be added.</remarks>
8686
</Docs>
8787
</Member>
@@ -104,10 +104,10 @@
104104
<ReturnType>THandle</ReturnType>
105105
</ReturnValue>
106106
<Docs>
107-
<summary>To be added.</summary>
108-
<value>To be added.</value>
107+
<summary>Gets the reserved blob handle.</summary>
108+
<value>The reserved bloc handle.</value>
109109
<remarks>To be added.</remarks>
110110
</Docs>
111111
</Member>
112112
</Members>
113-
</Type>
113+
</Type>

‎xml/System.Reflection.Metadata/StandaloneSignature.xml

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -204,9 +204,10 @@
204204
</ReturnValue>
205205
<Parameters />
206206
<Docs>
207-
<summary>To be added.</summary>
208-
<returns>To be added.</returns>
207+
<summary>Determines the kind of signature, which can be <see cref="F:System.Reflection.Metadata.SignatureKind.Method" /> or <see cref="F:System.Reflection.Metadata.SignatureKind.LocalVariables" />.</summary>
208+
<returns>An enumeration value that indicates the signature kind.</returns>
209209
<remarks>To be added.</remarks>
210+
<exception cref="T:System.BadImageFormatException">The signature is invalid.</exception>
210211
</Docs>
211212
</Member>
212213
<Member MemberName="Signature">
@@ -230,10 +231,10 @@
230231
<ReturnType>System.Reflection.Metadata.BlobHandle</ReturnType>
231232
</ReturnValue>
232233
<Docs>
233-
<summary>To be added.</summary>
234-
<value>To be added.</value>
234+
<summary>Gets a handle to the signature blob.</summary>
235+
<value>A handle to the signature blob.</value>
235236
<remarks>To be added.</remarks>
236237
</Docs>
237238
</Member>
238239
</Members>
239-
</Type>
240+
</Type>

0 commit comments

Comments
 (0)