Skip to content

Port System.Formats.Nrbf new docs #10168

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Jul 30, 2024
Merged

Port System.Formats.Nrbf new docs #10168

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
eb28f1a
System.Formats.Nrbf
Jul 26, 2024
6be3643
Update xml/System.Formats.Nrbf/SerializationRecord.xml
directhex Jul 30, 2024
0f42af5
Update xml/System.Formats.Nrbf/SerializationRecordType.xml
directhex Jul 30, 2024
38710ec
Update xml/System.Formats.Nrbf/ClassRecord.xml
directhex Jul 30, 2024
ebf0ecc
Update xml/System.Formats.Nrbf/ClassRecord.xml
directhex Jul 30, 2024
c026de2
Update xml/System.Formats.Nrbf/ClassRecord.xml
directhex Jul 30, 2024
52ab27f
Update xml/System.Formats.Nrbf/ClassRecord.xml
directhex Jul 30, 2024
5113810
Update xml/System.Formats.Nrbf/ClassRecord.xml
directhex Jul 30, 2024
eaa187d
Update xml/System.Formats.Nrbf/PrimitiveTypeRecord.xml
directhex Jul 30, 2024
096749b
Update xml/System.Formats.Nrbf/PrimitiveTypeRecord`1.xml
directhex Jul 30, 2024
f79f793
Update xml/System.Formats.Nrbf/SerializationRecordType.xml
directhex Jul 30, 2024
d94d79e
Update xml/System.Formats.Nrbf/SerializationRecordType.xml
directhex Jul 30, 2024
36ad9c9
Update xml/System.Formats.Nrbf/SerializationRecord.xml
directhex Jul 30, 2024
d46538a
Update xml/System.Formats.Nrbf/ClassRecord.xml
directhex Jul 30, 2024
38fb663
Update xml/System.Formats.Nrbf/NrbfDecoder.xml
directhex Jul 30, 2024
501333d
Update xml/System.Formats.Nrbf/PayloadOptions.xml
directhex Jul 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 13 additions & 9 deletions xml/System.Formats.Nrbf/ArrayRecord.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<summary>Defines the core behavior for NRBF array records and provides a base for derived classes.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand Down Expand Up @@ -47,11 +47,14 @@
<Parameter Name="allowNulls" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="expectedArrayType">To be added.</param>
<param name="allowNulls">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="expectedArrayType">Expected array type.</param>
<param name="allowNulls">
<see langword="true" /> to permit <see langword="null" /> values within the array; otherwise, <see langword="false" />.</param>
<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>
<returns>An array filled with the data provided in the serialized records.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.InvalidOperationException">
<paramref name="expectedArrayType" /> does not match the data from the payload.</exception>
</Docs>
</Member>
<Member MemberName="Id">
Expand All @@ -73,6 +76,7 @@
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<inheritdoc />
</Docs>
</Member>
<Member MemberName="Lengths">
Expand All @@ -91,8 +95,8 @@
<ReturnType>System.ReadOnlySpan&lt;System.Int32&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>When overridden in a derived class, gets a buffer of integers that represent the number of elements in every dimension.</summary>
<value>A buffer of integers that represent the number of elements in every dimension.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -112,8 +116,8 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the rank of the array.</summary>
<value>The rank of the array.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
64 changes: 50 additions & 14 deletions xml/System.Formats.Nrbf/ClassRecord.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
</Attribute>
</Attributes>
<Docs>
<summary>To be added.</summary>
<summary>Defines the core behavior for NRBF class records and provides a base for derived classes.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand Down Expand Up @@ -57,6 +57,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetBoolean">
Expand All @@ -82,6 +83,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetByte">
Expand All @@ -107,6 +109,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetChar">
Expand All @@ -132,6 +135,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetClassRecord">
Expand Down Expand Up @@ -159,10 +163,13 @@
<Parameter Name="memberName" Type="System.String" />
</Parameters>
<Docs>
<param name="memberName">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="memberName">The name of the member.</param>
<summary>Retrieves the value of the provided <paramref name="memberName" />.</summary>
<returns>The value.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.Collections.Generic.KeyNotFoundException">
<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>
<exception cref="T:System.InvalidOperationException">Member of such name has value of a different type.</exception>
</Docs>
</Member>
<Member MemberName="GetDateTime">
Expand All @@ -188,6 +195,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetDecimal">
Expand All @@ -213,6 +221,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetDouble">
Expand All @@ -238,6 +247,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetInt16">
Expand All @@ -263,6 +273,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetInt32">
Expand All @@ -288,6 +299,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetInt64">
Expand All @@ -313,6 +325,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetRawValue">
Expand Down Expand Up @@ -342,8 +355,15 @@
<Docs>
<param name="memberName">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<returns>
<para>For primitive types like <see cref="T:System.Int32" />, <see langword="string" /> or <see cref="T:System.DateTime" /> returns their value.</para>
<para>For nulls, returns a <see langword="null" />.</para>
<para>For other types that are not arrays, returns an instance of <see cref="T:System.Formats.Nrbf.ClassRecord" />.</para>
<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>
<para>For jagged and multi-dimensional arrays, returns an instance of <see cref="T:System.Formats.Nrbf.ArrayRecord" />.</para>
</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetSByte">
Expand All @@ -369,6 +389,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetSerializationRecord">
Expand Down Expand Up @@ -396,10 +417,13 @@
<Parameter Name="memberName" Type="System.String" />
</Parameters>
<Docs>
<param name="memberName">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="memberName">The name of the field.</param>
<summary>Retrieves the <see cref="T:System.Formats.Nrbf.SerializationRecord" /> of the provided <paramref name="memberName" />.</summary>
<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>
<remarks>To be added.</remarks>
<exception cref="T:System.Collections.Generic.KeyNotFoundException">
<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>
<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>
</Docs>
</Member>
<Member MemberName="GetSingle">
Expand All @@ -425,6 +449,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetString">
Expand Down Expand Up @@ -456,6 +481,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetTimeSpan">
Expand All @@ -481,6 +507,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetUInt16">
Expand All @@ -506,6 +533,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetUInt32">
Expand All @@ -531,6 +559,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="GetUInt64">
Expand All @@ -556,6 +585,7 @@
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.ClassRecord.GetClassRecord(System.String)" />
</Docs>
</Member>
<Member MemberName="HasMember">
Expand All @@ -577,10 +607,14 @@
<Parameter Name="memberName" Type="System.String" />
</Parameters>
<Docs>
<param name="memberName">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="memberName">The name of the member.</param>
<summary>Checks if member of given name was present in the payload.</summary>
<returns>
<see langword="true" /> if it was present, otherwise <see langword="false" />.</returns>
<remarks>
<para> It's recommended to use this method when dealing with payload that may contain different versions of the same type.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="Id">
Expand All @@ -602,6 +636,7 @@
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<inheritdoc />
</Docs>
</Member>
<Member MemberName="MemberNames">
Expand All @@ -620,8 +655,8 @@
<ReturnType>System.Collections.Generic.IEnumerable&lt;System.String&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the names of the serialized members.</summary>
<value>The names of the serialized members.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -644,6 +679,7 @@
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<inheritdoc />
</Docs>
</Member>
</Members>
Expand Down
52 changes: 36 additions & 16 deletions xml/System.Formats.Nrbf/NrbfDecoder.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
</Attribute>
</Attributes>
<Docs>
<summary>To be added.</summary>
<summary>Provides stateless methods for decoding .NET Remoting Binary Format (NRBF) encoded data.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand Down Expand Up @@ -55,12 +55,21 @@
<Parameter Name="leaveOpen" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="payload">To be added.</param>
<param name="options">To be added.</param>
<param name="leaveOpen">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="payload">The NRBF payload.</param>
<param name="options">Options to control behavior during parsing.</param>
<param name="leaveOpen">
<see langword="true" /> to leave <paramref name="payload" /> payload open after the reading is finished; otherwise, <see langword="false" />.</param>
<summary>Decodes the provided NRBF payload.</summary>
<returns>A <see cref="T:System.Formats.Nrbf.SerializationRecord" /> that represents the root object.
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>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="payload" /> is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentException">
<paramref name="payload" /> does not support reading or is already closed.</exception>
<exception cref="T:System.Runtime.Serialization.SerializationException">Reading from <paramref name="payload" /> encounters invalid NRBF data.</exception>
<exception cref="T:System.Text.DecoderFallbackException">Reading from <paramref name="payload" />
encounters an invalid UTF8 sequence.</exception>
</Docs>
</Member>
<Member MemberName="Decode">
Expand Down Expand Up @@ -92,13 +101,16 @@
<Parameter Name="leaveOpen" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="payload">To be added.</param>
<param name="recordMap">To be added.</param>
<param name="options">To be added.</param>
<param name="leaveOpen">To be added.</param>
<param name="payload">The NRBF payload.</param>
<param name="recordMap">When this method returns, contains a mapping of <see cref="T:System.Formats.Nrbf.SerializationRecordId" /> to the associated serialization record.
This parameter is treated as uninitialized.</param>
<param name="options">An object that describes optional <see cref="T:System.Formats.Nrbf.PayloadOptions" /> parameters to use.</param>
<param name="leaveOpen">
<see langword="true" /> to leave <paramref name="payload" /> payload open after the reading is finished; otherwise, <see langword="false" />.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.NrbfDecoder.Decode(System.IO.Stream,System.Formats.Nrbf.PayloadOptions,System.Boolean)" />
</Docs>
</Member>
<Member MemberName="DecodeClassRecord">
Expand Down Expand Up @@ -131,9 +143,10 @@
<param name="payload">To be added.</param>
<param name="options">To be added.</param>
<param name="leaveOpen">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<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>
<returns>A <see cref="T:System.Formats.Nrbf.ClassRecord" /> that represents the root object.</returns>
<remarks>To be added.</remarks>
<inheritdoc cref="M:System.Formats.Nrbf.NrbfDecoder.Decode(System.IO.Stream,System.Formats.Nrbf.PayloadOptions,System.Boolean)" />
</Docs>
</Member>
<Member MemberName="StartsWithPayloadHeader">
Expand Down Expand Up @@ -180,10 +193,17 @@
<Parameter Name="stream" Type="System.IO.Stream" />
</Parameters>
<Docs>
<param name="stream">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="stream">The stream to inspect. The stream must be both readable and seekable.</param>
<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>
<returns>
<see langword="true" /> if it starts with NRBF payload header; otherwise, <see langword="false" />.</returns>
<remarks>
<para>When this method returns, <paramref name="stream" /> will be restored to its original position.</para>
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="stream" /> is <see langword="null" />.</exception>
<exception cref="T:System.NotSupportedException">The stream does not support reading or seeking.</exception>
<exception cref="T:System.ObjectDisposedException">The stream was closed.</exception>
</Docs>
</Member>
</Members>
Expand Down
Loading