Skip to content

Commit 563e753

Browse files
directhexadamsitnikgewarren
authored
Port System.Formats.Nrbf new docs (#10168)
* System.Formats.Nrbf * Update xml/System.Formats.Nrbf/SerializationRecord.xml Co-authored-by: Adam Sitnik <[email protected]> * Update xml/System.Formats.Nrbf/SerializationRecordType.xml Co-authored-by: Adam Sitnik <[email protected]> * Update xml/System.Formats.Nrbf/ClassRecord.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/ClassRecord.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/ClassRecord.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/ClassRecord.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/ClassRecord.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/PrimitiveTypeRecord.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/PrimitiveTypeRecord`1.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/SerializationRecordType.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/SerializationRecordType.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/SerializationRecord.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/ClassRecord.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/NrbfDecoder.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Nrbf/PayloadOptions.xml Co-authored-by: Genevieve Warren <[email protected]> --------- Co-authored-by: Adam Sitnik <[email protected]> Co-authored-by: Genevieve Warren <[email protected]>
1 parent 7d3b728 commit 563e753

10 files changed

+179
-95
lines changed

‎xml/System.Formats.Nrbf/ArrayRecord.xml

Lines changed: 13 additions & 9 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>Defines the core behavior for NRBF array records and provides a base for derived classes.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -47,11 +47,14 @@
4747
<Parameter Name="allowNulls" Type="System.Boolean" />
4848
</Parameters>
4949
<Docs>
50-
<param name="expectedArrayType">To be added.</param>
51-
<param name="allowNulls">To be added.</param>
52-
<summary>To be added.</summary>
53-
<returns>To be added.</returns>
50+
<param name="expectedArrayType">Expected array type.</param>
51+
<param name="allowNulls">
52+
<see langword="true" /> to permit <see langword="null" /> values within the array; otherwise, <see langword="false" />.</param>
53+
<summary>Allocates an array and fills it with the data provided in the serialized records (in case of primitive types like <see cref="T:System.String" /> or <see cref="T:System.Int32" />) or the serialized records themselves.</summary>
54+
<returns>An array filled with the data provided in the serialized records.</returns>
5455
<remarks>To be added.</remarks>
56+
<exception cref="T:System.InvalidOperationException">
57+
<paramref name="expectedArrayType" /> does not match the data from the payload.</exception>
5558
</Docs>
5659
</Member>
5760
<Member MemberName="Id">
@@ -73,6 +76,7 @@
7376
<summary>To be added.</summary>
7477
<value>To be added.</value>
7578
<remarks>To be added.</remarks>
79+
<inheritdoc />
7680
</Docs>
7781
</Member>
7882
<Member MemberName="Lengths">
@@ -91,8 +95,8 @@
9195
<ReturnType>System.ReadOnlySpan&lt;System.Int32&gt;</ReturnType>
9296
</ReturnValue>
9397
<Docs>
94-
<summary>To be added.</summary>
95-
<value>To be added.</value>
98+
<summary>When overridden in a derived class, gets a buffer of integers that represent the number of elements in every dimension.</summary>
99+
<value>A buffer of integers that represent the number of elements in every dimension.</value>
96100
<remarks>To be added.</remarks>
97101
</Docs>
98102
</Member>
@@ -112,8 +116,8 @@
112116
<ReturnType>System.Int32</ReturnType>
113117
</ReturnValue>
114118
<Docs>
115-
<summary>To be added.</summary>
116-
<value>To be added.</value>
119+
<summary>Gets the rank of the array.</summary>
120+
<value>The rank of the array.</value>
117121
<remarks>To be added.</remarks>
118122
</Docs>
119123
</Member>

‎xml/System.Formats.Nrbf/ClassRecord.xml

Lines changed: 50 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
</Attribute>
2525
</Attributes>
2626
<Docs>
27-
<summary>To be added.</summary>
27+
<summary>Defines the core behavior for NRBF class records and provides a base for derived classes.</summary>
2828
<remarks>To be added.</remarks>
2929
</Docs>
3030
<Members>
@@ -57,6 +57,7 @@
5757
<summary>To be added.</summary>
5858
<returns>To be added.</returns>
5959
<remarks>To be added.</remarks>
60+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
6061
</Docs>
6162
</Member>
6263
<Member MemberName="GetBoolean">
@@ -82,6 +83,7 @@
8283
<summary>To be added.</summary>
8384
<returns>To be added.</returns>
8485
<remarks>To be added.</remarks>
86+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
8587
</Docs>
8688
</Member>
8789
<Member MemberName="GetByte">
@@ -107,6 +109,7 @@
107109
<summary>To be added.</summary>
108110
<returns>To be added.</returns>
109111
<remarks>To be added.</remarks>
112+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
110113
</Docs>
111114
</Member>
112115
<Member MemberName="GetChar">
@@ -132,6 +135,7 @@
132135
<summary>To be added.</summary>
133136
<returns>To be added.</returns>
134137
<remarks>To be added.</remarks>
138+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
135139
</Docs>
136140
</Member>
137141
<Member MemberName="GetClassRecord">
@@ -159,10 +163,13 @@
159163
<Parameter Name="memberName" Type="System.String" />
160164
</Parameters>
161165
<Docs>
162-
<param name="memberName">To be added.</param>
163-
<summary>To be added.</summary>
164-
<returns>To be added.</returns>
166+
<param name="memberName">The name of the member.</param>
167+
<summary>Retrieves the value of the provided <paramref name="memberName" />.</summary>
168+
<returns>The value of the provided <paramref name="memberName" />.</returns>
165169
<remarks>To be added.</remarks>
170+
<exception cref="T:System.Collections.Generic.KeyNotFoundException">
171+
<paramref name="memberName" /> does not refer to a known member. You can use <see cref="M:System.Formats.Nrbf.ClassRecord.HasMember(System.String)" /> to check if given member exists.</exception>
172+
<exception cref="T:System.InvalidOperationException">The member with the specified name has a value of a different type.</exception>
166173
</Docs>
167174
</Member>
168175
<Member MemberName="GetDateTime">
@@ -188,6 +195,7 @@
188195
<summary>To be added.</summary>
189196
<returns>To be added.</returns>
190197
<remarks>To be added.</remarks>
198+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
191199
</Docs>
192200
</Member>
193201
<Member MemberName="GetDecimal">
@@ -213,6 +221,7 @@
213221
<summary>To be added.</summary>
214222
<returns>To be added.</returns>
215223
<remarks>To be added.</remarks>
224+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
216225
</Docs>
217226
</Member>
218227
<Member MemberName="GetDouble">
@@ -238,6 +247,7 @@
238247
<summary>To be added.</summary>
239248
<returns>To be added.</returns>
240249
<remarks>To be added.</remarks>
250+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
241251
</Docs>
242252
</Member>
243253
<Member MemberName="GetInt16">
@@ -263,6 +273,7 @@
263273
<summary>To be added.</summary>
264274
<returns>To be added.</returns>
265275
<remarks>To be added.</remarks>
276+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
266277
</Docs>
267278
</Member>
268279
<Member MemberName="GetInt32">
@@ -288,6 +299,7 @@
288299
<summary>To be added.</summary>
289300
<returns>To be added.</returns>
290301
<remarks>To be added.</remarks>
302+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
291303
</Docs>
292304
</Member>
293305
<Member MemberName="GetInt64">
@@ -313,6 +325,7 @@
313325
<summary>To be added.</summary>
314326
<returns>To be added.</returns>
315327
<remarks>To be added.</remarks>
328+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
316329
</Docs>
317330
</Member>
318331
<Member MemberName="GetRawValue">
@@ -342,8 +355,15 @@
342355
<Docs>
343356
<param name="memberName">To be added.</param>
344357
<summary>To be added.</summary>
345-
<returns>To be added.</returns>
358+
<returns>
359+
<para>For primitive types like <see cref="T:System.Int32" />, <see langword="string" />, or <see cref="T:System.DateTime" />, returns their value.</para>
360+
<para>For nulls, returns a <see langword="null" />.</para>
361+
<para>For other types that are not arrays, returns an instance of <see cref="T:System.Formats.Nrbf.ClassRecord" />.</para>
362+
<para>For single-dimensional arrays, returns <see cref="T:System.Formats.Nrbf.SZArrayRecord`1" /> where the generic type is the primitive type or <see cref="T:System.Formats.Nrbf.ClassRecord" />.</para>
363+
<para>For jagged and multi-dimensional arrays, returns an instance of <see cref="T:System.Formats.Nrbf.ArrayRecord" />.</para>
364+
</returns>
346365
<remarks>To be added.</remarks>
366+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
347367
</Docs>
348368
</Member>
349369
<Member MemberName="GetSByte">
@@ -369,6 +389,7 @@
369389
<summary>To be added.</summary>
370390
<returns>To be added.</returns>
371391
<remarks>To be added.</remarks>
392+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
372393
</Docs>
373394
</Member>
374395
<Member MemberName="GetSerializationRecord">
@@ -396,10 +417,13 @@
396417
<Parameter Name="memberName" Type="System.String" />
397418
</Parameters>
398419
<Docs>
399-
<param name="memberName">To be added.</param>
400-
<summary>To be added.</summary>
401-
<returns>To be added.</returns>
420+
<param name="memberName">The name of the field.</param>
421+
<summary>Retrieves the <see cref="T:System.Formats.Nrbf.SerializationRecord" /> of the provided <paramref name="memberName" />.</summary>
422+
<returns>The serialization record, which can be any of <see cref="T:System.Formats.Nrbf.PrimitiveTypeRecord`1" />, <see cref="T:System.Formats.Nrbf.ClassRecord" />, <see cref="T:System.Formats.Nrbf.ArrayRecord" />, or <see langword="null" />.</returns>
402423
<remarks>To be added.</remarks>
424+
<exception cref="T:System.Collections.Generic.KeyNotFoundException">
425+
<paramref name="memberName" /> does not refer to a known member. You can use <see cref="M:System.Formats.Nrbf.ClassRecord.HasMember(System.String)" /> to check if given member exists.</exception>
426+
<exception cref="T:System.InvalidOperationException">The specified member is not a <see cref="T:System.Formats.Nrbf.SerializationRecord" />, but just a raw primitive value.</exception>
403427
</Docs>
404428
</Member>
405429
<Member MemberName="GetSingle">
@@ -425,6 +449,7 @@
425449
<summary>To be added.</summary>
426450
<returns>To be added.</returns>
427451
<remarks>To be added.</remarks>
452+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
428453
</Docs>
429454
</Member>
430455
<Member MemberName="GetString">
@@ -456,6 +481,7 @@
456481
<summary>To be added.</summary>
457482
<returns>To be added.</returns>
458483
<remarks>To be added.</remarks>
484+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
459485
</Docs>
460486
</Member>
461487
<Member MemberName="GetTimeSpan">
@@ -481,6 +507,7 @@
481507
<summary>To be added.</summary>
482508
<returns>To be added.</returns>
483509
<remarks>To be added.</remarks>
510+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
484511
</Docs>
485512
</Member>
486513
<Member MemberName="GetUInt16">
@@ -506,6 +533,7 @@
506533
<summary>To be added.</summary>
507534
<returns>To be added.</returns>
508535
<remarks>To be added.</remarks>
536+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
509537
</Docs>
510538
</Member>
511539
<Member MemberName="GetUInt32">
@@ -531,6 +559,7 @@
531559
<summary>To be added.</summary>
532560
<returns>To be added.</returns>
533561
<remarks>To be added.</remarks>
562+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
534563
</Docs>
535564
</Member>
536565
<Member MemberName="GetUInt64">
@@ -556,6 +585,7 @@
556585
<summary>To be added.</summary>
557586
<returns>To be added.</returns>
558587
<remarks>To be added.</remarks>
588+
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
559589
</Docs>
560590
</Member>
561591
<Member MemberName="HasMember">
@@ -577,10 +607,14 @@
577607
<Parameter Name="memberName" Type="System.String" />
578608
</Parameters>
579609
<Docs>
580-
<param name="memberName">To be added.</param>
581-
<summary>To be added.</summary>
582-
<returns>To be added.</returns>
583-
<remarks>To be added.</remarks>
610+
<param name="memberName">The name of the member.</param>
611+
<summary>Checks if member of given name was present in the payload.</summary>
612+
<returns>
613+
<see langword="true" /> if it was present, otherwise <see langword="false" />.</returns>
614+
<remarks>
615+
<para> It's recommended to use this method when dealing with payload that might contain different versions of the same type.
616+
</para>
617+
</remarks>
584618
</Docs>
585619
</Member>
586620
<Member MemberName="Id">
@@ -602,6 +636,7 @@
602636
<summary>To be added.</summary>
603637
<value>To be added.</value>
604638
<remarks>To be added.</remarks>
639+
<inheritdoc />
605640
</Docs>
606641
</Member>
607642
<Member MemberName="MemberNames">
@@ -620,8 +655,8 @@
620655
<ReturnType>System.Collections.Generic.IEnumerable&lt;System.String&gt;</ReturnType>
621656
</ReturnValue>
622657
<Docs>
623-
<summary>To be added.</summary>
624-
<value>To be added.</value>
658+
<summary>Gets the names of the serialized members.</summary>
659+
<value>The names of the serialized members.</value>
625660
<remarks>To be added.</remarks>
626661
</Docs>
627662
</Member>
@@ -644,6 +679,7 @@
644679
<summary>To be added.</summary>
645680
<value>To be added.</value>
646681
<remarks>To be added.</remarks>
682+
<inheritdoc />
647683
</Docs>
648684
</Member>
649685
</Members>

‎xml/System.Formats.Nrbf/NrbfDecoder.xml

Lines changed: 36 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
</Attribute>
2525
</Attributes>
2626
<Docs>
27-
<summary>To be added.</summary>
27+
<summary>Provides stateless methods for decoding .NET Remoting Binary Format (NRBF) encoded data.</summary>
2828
<remarks>To be added.</remarks>
2929
</Docs>
3030
<Members>
@@ -55,12 +55,21 @@
5555
<Parameter Name="leaveOpen" Type="System.Boolean" />
5656
</Parameters>
5757
<Docs>
58-
<param name="payload">To be added.</param>
59-
<param name="options">To be added.</param>
60-
<param name="leaveOpen">To be added.</param>
61-
<summary>To be added.</summary>
62-
<returns>To be added.</returns>
58+
<param name="payload">The NRBF payload.</param>
59+
<param name="options">Options to control behavior during parsing.</param>
60+
<param name="leaveOpen">
61+
<see langword="true" /> to leave <paramref name="payload" /> payload open after the reading is finished; otherwise, <see langword="false" />.</param>
62+
<summary>Decodes the provided NRBF payload.</summary>
63+
<returns>A <see cref="T:System.Formats.Nrbf.SerializationRecord" /> that represents the root object.
64+
It can be either <see cref="T:System.Formats.Nrbf.PrimitiveTypeRecord`1" />, a <see cref="T:System.Formats.Nrbf.ClassRecord" />, or an <see cref="T:System.Formats.Nrbf.ArrayRecord" />.</returns>
6365
<remarks>To be added.</remarks>
66+
<exception cref="T:System.ArgumentNullException">
67+
<paramref name="payload" /> is <see langword="null" />.</exception>
68+
<exception cref="T:System.ArgumentException">
69+
<paramref name="payload" /> does not support reading or is already closed.</exception>
70+
<exception cref="T:System.Runtime.Serialization.SerializationException">Reading from <paramref name="payload" /> encounters invalid NRBF data.</exception>
71+
<exception cref="T:System.Text.DecoderFallbackException">Reading from <paramref name="payload" />
72+
encounters an invalid UTF8 sequence.</exception>
6473
</Docs>
6574
</Member>
6675
<Member MemberName="Decode">
@@ -92,13 +101,16 @@
92101
<Parameter Name="leaveOpen" Type="System.Boolean" />
93102
</Parameters>
94103
<Docs>
95-
<param name="payload">To be added.</param>
96-
<param name="recordMap">To be added.</param>
97-
<param name="options">To be added.</param>
98-
<param name="leaveOpen">To be added.</param>
104+
<param name="payload">The NRBF payload.</param>
105+
<param name="recordMap">When this method returns, contains a mapping of <see cref="T:System.Formats.Nrbf.SerializationRecordId" /> to the associated serialization record.
106+
This parameter is treated as uninitialized.</param>
107+
<param name="options">An object that describes optional <see cref="T:System.Formats.Nrbf.PayloadOptions" /> parameters to use.</param>
108+
<param name="leaveOpen">
109+
<see langword="true" /> to leave <paramref name="payload" /> payload open after the reading is finished; otherwise, <see langword="false" />.</param>
99110
<summary>To be added.</summary>
100111
<returns>To be added.</returns>
101112
<remarks>To be added.</remarks>
113+
<inheritdoc cref="M:System.Formats.Nrbf.NrbfDecoder.Decode(System.IO.Stream,System.Formats.Nrbf.PayloadOptions,System.Boolean)" />
102114
</Docs>
103115
</Member>
104116
<Member MemberName="DecodeClassRecord">
@@ -131,9 +143,10 @@
131143
<param name="payload">To be added.</param>
132144
<param name="options">To be added.</param>
133145
<param name="leaveOpen">To be added.</param>
134-
<summary>To be added.</summary>
135-
<returns>To be added.</returns>
146+
<summary>Decodes the provided NRBF payload that is expected to contain an instance of any class (or struct) that is not an <see cref="T:System.Array" /> or a primitive type.</summary>
147+
<returns>A <see cref="T:System.Formats.Nrbf.ClassRecord" /> that represents the root object.</returns>
136148
<remarks>To be added.</remarks>
149+
<inheritdoc cref="M:System.Formats.Nrbf.NrbfDecoder.Decode(System.IO.Stream,System.Formats.Nrbf.PayloadOptions,System.Boolean)" />
137150
</Docs>
138151
</Member>
139152
<Member MemberName="StartsWithPayloadHeader">
@@ -180,10 +193,17 @@
180193
<Parameter Name="stream" Type="System.IO.Stream" />
181194
</Parameters>
182195
<Docs>
183-
<param name="stream">To be added.</param>
184-
<summary>To be added.</summary>
185-
<returns>To be added.</returns>
186-
<remarks>To be added.</remarks>
196+
<param name="stream">The stream to inspect. The stream must be both readable and seekable.</param>
197+
<summary>Checks if given stream starts with <see href="https://learn.microsoft.com/openspecs/windows_protocols/ms-nrbf/a7e578d3-400a-4249-9424-7529d10d1b3c">NRBF payload header</see>.</summary>
198+
<returns>
199+
<see langword="true" /> if it starts with NRBF payload header; otherwise, <see langword="false" />.</returns>
200+
<remarks>
201+
<para>When this method returns, <paramref name="stream" /> will be restored to its original position.</para>
202+
</remarks>
203+
<exception cref="T:System.ArgumentNullException">
204+
<paramref name="stream" /> is <see langword="null" />.</exception>
205+
<exception cref="T:System.NotSupportedException">The stream does not support reading or seeking.</exception>
206+
<exception cref="T:System.ObjectDisposedException">The stream was closed.</exception>
187207
</Docs>
188208
</Member>
189209
</Members>

0 commit comments

Comments
 (0)