Skip to content

Commit 74587ec

Browse files
carlossanlopcarlossanlop
committed
Automatically port System.Text.Json triple slash comments
1 parent f95f9de commit 74587ec

11 files changed

+799
-260
lines changed

‎xml/System.Text.Json.Serialization/JsonAttribute.xml

Lines changed: 2 additions & 2 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>The base class of serialization attributes.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -31,7 +31,7 @@
3131
</AssemblyInfo>
3232
<Parameters />
3333
<Docs>
34-
<summary>To be added.</summary>
34+
<summary>Creates a JsonAttribute instance.</summary>
3535
<remarks>To be added.</remarks>
3636
</Docs>
3737
</Member>

‎xml/System.Text.Json.Serialization/JsonExtensionDataAttribute.xml

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,24 @@
1919
</Attribute>
2020
</Attributes>
2121
<Docs>
22-
<summary>To be added.</summary>
23-
<remarks>To be added.</remarks>
22+
<summary>When placed on a property of type <see cref="T:System.Collections.Generic.IDictionary`2" />, any properties that do not have a matching member are added to that Dictionary during deserialization and written during serialization.</summary>
23+
<remarks>
24+
<format type="text/markdown">
25+
<![CDATA[
26+
27+
## Remarks
28+
29+
The TKey value must be <xref:System.String> and TValue must be <xref:System.Text.Json.JsonElement> or <xref:System.Object>.
30+
31+
During deserializing, when using <xref:System.Object> a "null" JSON value is treated as a `null` object reference, and when using <xref:System.Text.Json.JsonElement> a "null" is treated as a JsonElement with <xref:System.Text.Json.JsonElement.ValueKind> set to <xref:System.Text.Json.JsonValueKind.Null>.
32+
33+
During serializing, the name of the extension data property is not included in the JSON; the data contained within the extension data is serialized as properties of the JSON object.
34+
35+
If there is more than one extension property on a type, or it the property is not of the correct type, an <xref:System.InvalidOperationException> is thrown during the first serialization or deserialization of that type.
36+
37+
]]>
38+
</format>
39+
</remarks>
2440
</Docs>
2541
<Members>
2642
<Member MemberName=".ctor">

‎xml/System.Text.Json.Serialization/JsonIgnoreAttribute.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
</Attribute>
2020
</Attributes>
2121
<Docs>
22-
<summary>To be added.</summary>
22+
<summary>Prevents a property from being serialized or deserialized.</summary>
2323
<remarks>To be added.</remarks>
2424
</Docs>
2525
<Members>
@@ -36,7 +36,7 @@
3636
</AssemblyInfo>
3737
<Parameters />
3838
<Docs>
39-
<summary>To be added.</summary>
39+
<summary>Initializes a new instance of <see cref="T:System.Text.Json.Serialization.JsonIgnoreAttribute" />.</summary>
4040
<remarks>To be added.</remarks>
4141
</Docs>
4242
</Member>

‎xml/System.Text.Json.Serialization/JsonPropertyNameAttribute.xml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
</Attribute>
2020
</Attributes>
2121
<Docs>
22-
<summary>To be added.</summary>
22+
<summary>Specifies the property name that is present in the JSON when serializing and deserializing. This overrides any naming policy specified by <see cref="T:System.Text.Json.JsonNamingPolicy" />.</summary>
2323
<remarks>To be added.</remarks>
2424
</Docs>
2525
<Members>
@@ -39,8 +39,8 @@
3939
<Parameter Name="name" Type="System.String" />
4040
</Parameters>
4141
<Docs>
42-
<param name="name">To be added.</param>
43-
<summary>To be added.</summary>
42+
<param name="name">The name of the property.</param>
43+
<summary>Initializes a new instance of <see cref="T:System.Text.Json.Serialization.JsonPropertyNameAttribute" /> with the specified property name.</summary>
4444
<remarks>To be added.</remarks>
4545
</Docs>
4646
</Member>
@@ -60,8 +60,8 @@
6060
<ReturnType>System.String</ReturnType>
6161
</ReturnValue>
6262
<Docs>
63-
<summary>To be added.</summary>
64-
<value>To be added.</value>
63+
<summary>The name of the property.</summary>
64+
<value>A string representing the name of the property.</value>
6565
<remarks>To be added.</remarks>
6666
</Docs>
6767
</Member>

‎xml/System.Text.Json/JsonElement.xml

Lines changed: 63 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -170,9 +170,22 @@ This method does not parse the contents of a JSON string value.
170170
</ReturnValue>
171171
<Parameters />
172172
<Docs>
173-
<summary>To be added.</summary>
174-
<returns>To be added.</returns>
175-
<remarks>To be added.</remarks>
173+
<summary>Gets the value of the element as bytes.</summary>
174+
<returns>The value decode to bytes.</returns>
175+
<remarks>
176+
<format type="text/markdown">
177+
<![CDATA[
178+
179+
## Remarks
180+
181+
This method does not create a byte[] representation of values other than base 64 encoded JSON strings.
182+
183+
]]>
184+
</format>
185+
</remarks>
186+
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.ValueKind" /> is not <see cref="F:System.Text.Json.JsonValueKind.String" />.</exception>
187+
<exception cref="T:System.FormatException">The value is not encoded as base 64 text and hence cannot be decoded to bytes.</exception>
188+
<exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
176189
</Docs>
177190
</Member>
178191
<Member MemberName="GetDateTime">
@@ -260,7 +273,7 @@ This method does not create a DateTimeOffset representation of values other than
260273
<format><![CDATA[
261274
262275
This method does not parse the contents of a JSON string value.
263-
276+
264277
]]></format>
265278
</remarks>
266279
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Number" />.</exception>
@@ -293,8 +306,8 @@ This method does not create a DateTimeOffset representation of values other than
293306
This method does not parse the contents of a JSON string value.
294307
295308
On .NET Core, this method returns <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> for values larger than <xref:System.Double.MaxValue?displayProperty=nameWithType>, and it returns <xref:System.Double.NegativeInfinity?displayProperty=nameWithType> for values smaller than <xref:System.Double.MinValue?displayProperty=nameWithType>.
296-
297-
]]></format>
309+
310+
]]></format>
298311
</remarks>
299312
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Number" />.</exception>
300313
<exception cref="T:System.FormatException">The value cannot be represented as a <see cref="T:System.Double" />.</exception>
@@ -324,7 +337,7 @@ On .NET Core, this method returns <xref:System.Double.PositiveInfinity?displayPr
324337
<format><![CDATA[
325338
326339
This method does not create a Guid representation of values other than JSON strings.
327-
340+
328341
]]></format>
329342
</remarks>
330343
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.String" />.</exception>
@@ -380,7 +393,7 @@ This method does not create a Guid representation of values other than JSON stri
380393
<format><![CDATA[
381394
382395
This method does not parse the contents of a JSON string value.
383-
396+
384397
]]></format>
385398
</remarks>
386399
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Number" />.</exception>
@@ -416,8 +429,8 @@ This method does not parse the contents of a JSON string value.
416429
Property name matching is performed as an ordinal, case-sensitive comparison.
417430
418431
If a property is defined multiple times for the same object, the method matches the last such definition.
419-
420-
]]></format>
432+
433+
]]></format>
421434
</remarks>
422435
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Object" />.</exception>
423436
<exception cref="T:System.Collections.Generic.KeyNotFoundException">No property was found with the requested name.</exception>
@@ -452,8 +465,8 @@ If a property is defined multiple times for the same object, the method matches
452465
Property name matching is performed as an ordinal, case-sensitive comparison.
453466
454467
If a property is defined multiple times for the same object, the method matches the last such definition.
455-
456-
]]></format>
468+
469+
]]></format>
457470
</remarks>
458471
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Object" />.</exception>
459472
<exception cref="T:System.Collections.Generic.KeyNotFoundException">No property was found with the requested name.</exception>
@@ -493,8 +506,7 @@ If a property is defined multiple times for the same object, the method matches
493506
</remarks>
494507
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Object" />.</exception>
495508
<exception cref="T:System.Collections.Generic.KeyNotFoundException">No property was found with the requested name.</exception>
496-
<exception cref="T:System.ArgumentNullException">
497-
<paramref name="propertyName" /> is <see langword="null" />.</exception>
509+
<exception cref="T:System.ArgumentNullException"><paramref name="propertyName" /> is <see langword="null" />.</exception>
498510
<exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
499511
</Docs>
500512
</Member>
@@ -546,8 +558,8 @@ If a property is defined multiple times for the same object, the method matches
546558
This method does not parse the contents of a JSON string value.
547559
548560
On .NET Core, this method returns <xref:System.Single.PositiveInfinity?displayProperty=nameWithType> for values larger than <xref:System.Single.MaxValue?displayProperty=nameWithType> and <xref:System.Single.NegativeInfinity?displayProperty=nameWithType> for values smaller than <xref:System.Single.MinValue?displayProperty=nameWithType>.
549-
550-
]]></format>
561+
562+
]]></format>
551563
</remarks>
552564
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Number" />.</exception>
553565
<exception cref="T:System.FormatException">The value cannot be represented as a <see cref="T:System.Single" />.</exception>
@@ -680,8 +692,7 @@ This method does not parse the contents of a JSON string value.
680692
<value>To be added.</value>
681693
<remarks>To be added.</remarks>
682694
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Array" />.</exception>
683-
<exception cref="T:System.IndexOutOfRangeException">
684-
<paramref name="index" /> is not in the range [0, <see cref="M:System.Text.Json.JsonElement.GetArrayLength" />()).</exception>
695+
<exception cref="T:System.IndexOutOfRangeException"><paramref name="index" /> is not in the range [0, <see cref="M:System.Text.Json.JsonElement.GetArrayLength" />()).</exception>
685696
<exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
686697
</Docs>
687698
</Member>
@@ -716,8 +727,8 @@ For <xref:System.Text.Json.JsonValueType.False?displayProperty=nameWithType>, <x
716727
For <xref:System.Text.Json.JsonValueType.String?displayProperty=nameWithType>, the value of <xref:System.Text.Json.JsonElement.GetString> is returned.
717728
718729
For other types, the value of <xref:System.Text.Json.JsonElement.GetRawText> is returned.
719-
720-
]]></format>
730+
731+
]]></format>
721732
</remarks>
722733
<exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
723734
</Docs>
@@ -741,10 +752,24 @@ For other types, the value of <xref:System.Text.Json.JsonElement.GetRawText> is
741752
<Parameter Name="value" Type="System.Byte[]" RefType="out" />
742753
</Parameters>
743754
<Docs>
744-
<param name="value">To be added.</param>
745-
<summary>To be added.</summary>
746-
<returns>To be added.</returns>
747-
<remarks>To be added.</remarks>
755+
<param name="value">Receives the value.</param>
756+
<summary>Attempts to represent the current JSON string as bytes assuming it is base 64 encoded.</summary>
757+
<returns>
758+
<see langword="true" /> if the entire token value is encoded as valid base 64 text and can be successfully decoded to bytes.
759+
<see langword="false" /> otherwise.</returns>
760+
<remarks>
761+
<format type="text/markdown">
762+
<![CDATA[
763+
764+
## Remarks
765+
766+
This method does not create a byte[] representation of values other than bsae 64 encoded JSON strings.
767+
768+
]]>
769+
</format>
770+
</remarks>
771+
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.ValueKind" /> is not <see cref="F:System.Text.Json.JsonValueKind.String" />.</exception>
772+
<exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
748773
</Docs>
749774
</Member>
750775
<Member MemberName="TryGetDateTime">
@@ -772,7 +797,7 @@ For other types, the value of <xref:System.Text.Json.JsonElement.GetRawText> is
772797
<see langword="true" /> if the string can be represented as a <see cref="T:System.DateTime" />, <see langword="false" /> otherwise.</returns>
773798
<remarks>
774799
<format><![CDATA[
775-
800+
776801
This method does not create a DateTime representation of values other than JSON strings.
777802
778803
]]></format>
@@ -808,7 +833,7 @@ This method does not create a DateTime representation of values other than JSON
808833
<format><![CDATA[
809834
810835
This method does not create a DateTimeOffset representation of values other than JSON strings.
811-
836+
812837
]]></format>
813838
</remarks>
814839
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.String" />.</exception>
@@ -878,8 +903,8 @@ This method does not parse the contents of a JSON string value.
878903
This method does not parse the contents of a JSON string value.
879904
880905
On .NET Core, this method does not return `false` for values larger than <xref:System.Double.MaxValue?displayProperty=nameWithType> or smaller than <xref:System.Double.MinValue?displayProperty=nameWithType>. Instead, it returns <see langword="true> and assigns <xref:System.Double.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Double.NegativeInfinity?displayProperty=nameWithType> to `value`.
881-
882-
]]></format>
906+
907+
]]></format>
883908
</remarks>
884909
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Number" />.</exception>
885910
<exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
@@ -912,7 +937,7 @@ On .NET Core, this method does not return `false` for values larger than <xref:S
912937
<format><![CDATA[
913938
914939
This method does not create a Guid representation of values other than JSON strings.
915-
940+
916941
]]></format>
917942
</remarks>
918943
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.String" />.</exception>
@@ -1018,8 +1043,8 @@ This method does not parse the contents of a JSON string value.
10181043
Property name matching is performed as an ordinal, case-sensitive comparison.
10191044
10201045
If a property is defined multiple times for the same object, the method matches the last such definition.
1021-
1022-
]]></format>
1046+
1047+
]]></format>
10231048
</remarks>
10241049
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Object" />.</exception>
10251050
<exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
@@ -1056,8 +1081,8 @@ If a property is defined multiple times for the same object, the method matches
10561081
Property name matching is performed as an ordinal, case-sensitive comparison.
10571082
10581083
If a property is defined multiple times for the same object, the method matches the last such definition.
1059-
1060-
]]></format>
1084+
1085+
]]></format>
10611086
</remarks>
10621087
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Object" />.</exception>
10631088
<exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
@@ -1094,12 +1119,11 @@ If a property is defined multiple times for the same object, the method matches
10941119
Property name matching is performed as an ordinal, case-sensitive comparison.
10951120
10961121
If a property is defined multiple times for the same object, the method matches the last such definition.
1097-
1098-
]]></format>
1122+
1123+
]]></format>
10991124
</remarks>
11001125
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Object" />.</exception>
1101-
<exception cref="T:System.ArgumentNullException">
1102-
<paramref name="propertyName" /> is <see langword="null" />.</exception>
1126+
<exception cref="T:System.ArgumentNullException"><paramref name="propertyName" /> is <see langword="null" />.</exception>
11031127
<exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>
11041128
</Docs>
11051129
</Member>
@@ -1132,8 +1156,8 @@ If a property is defined multiple times for the same object, the method matches
11321156
This method does not parse the contents of a JSON string value.
11331157
11341158
On .NET Core, this method does not return `false` for values larger than <xref:System.Single.MaxValue?displayProperty=nameWithType> or smaller than <xref:System.Single.MinValue?displayProperty=nameWithType>). Instead, it returns `false` and assigns <xref:System.Single.PositiveInfinity?displayProperty=nameWithType> or <xref:System.Single.NegativeInfinity?displayProperty=nameWithType> to the `value` argument.
1135-
1136-
]]></format>
1159+
1160+
]]></format>
11371161
</remarks>
11381162
<exception cref="T:System.InvalidOperationException">This value's <see cref="P:System.Text.Json.JsonElement.Type" /> is not <see cref="F:System.Text.Json.JsonValueType.Number" />.</exception>
11391163
<exception cref="T:System.ObjectDisposedException">The parent <see cref="T:System.Text.Json.JsonDocument" /> has been disposed.</exception>

0 commit comments

Comments
 (0)