Skip to content

Automatically port 5.0 System.Text.Json documentation #4284

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 5 commits into from
Aug 3, 2020
Merged

Automatically port 5.0 System.Text.Json documentation #4284

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6599488
Automatically port System.Text.Json 5.0 documentation
carlossanlop May 26, 2020
93f1dd8
Auto ported exceptions
carlossanlop May 26, 2020
bea6f8f
Apply suggestions from code review
carlossanlop Jun 23, 2020
5724b4d
Apply suggestions from code review
gewarren Aug 3, 2020
8f3ae36
pull upstream master
gewarren Aug 3, 2020
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
4 changes: 2 additions & 2 deletions xml/System.Text.Json.Serialization/JsonConstructorAttribute.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
</Attribute>
</Attributes>
<Docs>
<summary>To be added.</summary>
<summary>When placed on a constructor, indicates that the constructor should be used to create instances of the type on deserialization.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -37,7 +37,7 @@
</AssemblyInfo>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Initializes a new instance of <see cref="T:System.Text.Json.Serialization.JsonConstructorAttribute" />.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
12 changes: 10 additions & 2 deletions xml/System.Text.Json.Serialization/JsonIgnoreAttribute.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,9 +69,17 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa
<ReturnType>System.Text.Json.Serialization.JsonIgnoreCondition</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Specifies the condition that must be met before a property will be ignored.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The default value is <xref:System.Text.Json.Serialization.JsonIgnoreCondition.Always>.

]]></format>
</remarks>
</Docs>
</Member>
</Members>
Expand Down
11 changes: 7 additions & 4 deletions xml/System.Text.Json.Serialization/JsonIgnoreCondition.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
<BaseTypeName>System.Enum</BaseTypeName>
</Base>
<Docs>
<summary>To be added.</summary>
<summary>Controls how the <see cref="T:System.Text.Json.Serialization.JsonIgnoreAttribute" /> ignores properties on serialization and deserialization.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -34,7 +34,8 @@
</ReturnValue>
<MemberValue>1</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>Property will always be ignored.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="Never">
Expand All @@ -54,7 +55,8 @@
</ReturnValue>
<MemberValue>0</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>Property will always be serialized and deserialized, regardless of <see cref="P:System.Text.Json.JsonSerializerOptions.IgnoreNullValues" /> configuration.</summary>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<summary>Property will always be serialized and deserialized, regardless of <see cref="P:System.Text.Json.JsonSerializerOptions.IgnoreNullValues" /> configuration.</summary>
<summary>Property will always be serialized and deserialized, regardless of <see cref="P:System.Text.Json.JsonSerializerOptions.DefaultIgnoreCondition" /> configuration.</summary>

This will need to be changed when the docs for this property are added - https://github.com/dotnet/runtime/blob/master/src/libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonSerializerOptions.cs#L239.

<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="WhenWritingDefault">
Expand All @@ -74,7 +76,8 @@
</ReturnValue>
<MemberValue>2</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>Property will only be ignored if it is <see langword="null" />.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
</Members>
Expand Down
15 changes: 12 additions & 3 deletions xml/System.Text.Json.Serialization/JsonIncludeAttribute.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,17 @@
</Attribute>
</Attributes>
<Docs>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<summary>Indicates that the member should be included for serialization and deserialization.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

When applied to a property, indicates that non-public getters and setters can be used for serialization and deserialization. Non-public properties are not supported.

]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The attribute is applied to a non-public property.</exception>
</Docs>
<Members>
<Member MemberName=".ctor">
Expand All @@ -37,7 +46,7 @@
</AssemblyInfo>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Initializes a new instance of <see cref="T:System.Text.Json.Serialization.JsonIncludeAttribute" />.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
10 changes: 9 additions & 1 deletion xml/System.Text.Json/JsonElement+ArrayEnumerator.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -260,7 +260,15 @@ This member is an explicit interface member implementation. It can be used only
<Docs>
<summary>Gets the element in the collection at the current position of the enumerator.</summary>
<value>The element in the collection at the current position of the enumerator.</value>
<remarks>To be added.</remarks>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.Text.Json.JsonElement.ArrayEnumerator> instance is cast to an <xref:System.Collections.IEnumerator> interface.

]]></format>
</remarks>
</Docs>
</Member>
</Members>
Expand Down
10 changes: 9 additions & 1 deletion xml/System.Text.Json/JsonElement+ObjectEnumerator.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,15 @@ This member is an explicit interface member implementation. It can be used only
<Docs>
<summary>Gets the element in the collection at the current position of the enumerator.</summary>
<value>The element in the collection at the current position of the enumerator.</value>
<remarks>To be added.</remarks>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This member is an explicit interface member implementation. It can be used only when the <xref:System.Text.Json.JsonElement.ObjectEnumerator> instance is cast to an <xref:System.Collections.IEnumerator> interface.

]]></format>
</remarks>
</Docs>
</Member>
</Members>
Expand Down
2 changes: 2 additions & 0 deletions xml/System.Text.Json/JsonSerializer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,8 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa

There is remaining data in the stream.</exception>
<exception cref="T:System.NotSupportedException">There is no compatible <see cref="System.Text.Json.Serialization.JsonConverter" /> for <typeparamref name="TValue" /> or its serializable members.</exception>
<exception cref="T:System.ArgumentNullException">
<paramref name="utf8Json" />is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="Serialize">
Expand Down
10 changes: 6 additions & 4 deletions xml/System.Text.Json/JsonSerializerOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,9 +84,11 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa
<Parameter Name="options" Type="System.Text.Json.JsonSerializerOptions" Index="0" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="options">To be added.</param>
<summary>To be added.</summary>
<param name="options">The options instance to copy options from.</param>
<summary>Copies the options from a <see cref="T:System.Text.Json.JsonSerializerOptions" /> instance to a new instance.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="options" /> is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="AllowTrailingCommas">
Expand Down Expand Up @@ -547,9 +549,9 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa
<ReturnType>System.Text.Json.Serialization.ReferenceHandler</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Configures how object references are handled when reading and writing JSON.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<remarks>This option provides a convenient way to deal with circularity in object graphs.</remarks>
</Docs>
</Member>
<Member MemberName="WriteIndented">
Expand Down
22 changes: 19 additions & 3 deletions xml/System.Text.Json/Utf8JsonReader.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -350,7 +350,15 @@ The JSON token value represents a number less than <see cref="F:System.Byte.MinV
<returns>The byte array that represents the current JSON token value.</returns>
<remarks>To be added.</remarks>
<exception cref="T:System.InvalidOperationException">The type of the JSON token is not a <see cref="F:System.Text.Json.JsonTokenType.String" />.</exception>
<exception cref="T:System.FormatException">The value is not encoded as Base64 text, so it can't be decoded to bytes.</exception>
<exception cref="T:System.FormatException">The value is not encoded as Base64 text, so it can't be decoded to bytes.

-or-

The value contains invalid or more than two padding characters.

-or-

The value is incomplete. That is, the JSON string length is not a multiple of 4.</exception>
<altmember cref="P:System.Text.Json.Utf8JsonReader.TokenType" />
</Docs>
</Member>
Expand Down Expand Up @@ -415,7 +423,11 @@ This method only creates a <xref:System.DateTime> representation of JSON strings

-or-

The entire UTF-8 encoded token value cannot be parsed to a <see cref="T:System.DateTime" /> value.</exception>
The entire UTF-8 encoded token value cannot be parsed to a <see cref="T:System.DateTime" /> value.

-or-

The JSON token value is of an unsupported format.</exception>
<altmember cref="P:System.Text.Json.Utf8JsonReader.TokenType" />
</Docs>
</Member>
Expand Down Expand Up @@ -454,7 +466,11 @@ This method only creates a <xref:System.DateTimeOffset> representation of JSON s

-or-

The entire UTF-8 encoded token value cannot be parsed to a <see cref="T:System.DateTimeOffset" /> value.</exception>
The entire UTF-8 encoded token value cannot be parsed to a <see cref="T:System.DateTimeOffset" /> value.

-or-

The JSON token value is of an unsupported format.</exception>
<altmember cref="P:System.Text.Json.Utf8JsonReader.TokenType" />
</Docs>
</Member>
Expand Down