Skip to content

Commit a758205

Browse files
carlossanlopRon Petrusha
carlossanlop
authored and
Ron Petrusha
committed
Automatically port System.Text.Json triple slash comments (#2737)
* Automatically port System.Text.Json triple slash comments * Update JsonAttribute.xml * Update JsonExtensionDataAttribute.xml * Update JsonPropertyNameAttribute.xml * Update JsonExtensionDataAttribute.xml * Update JsonElement.xml * Update JsonEncodedText.xml * Update JsonException.xml * Update JsonReaderOptions.xml * Update JsonTokenType.xml * Update Utf8JsonReader.xml * suggestions by rpetrusha Co-Authored-By: Ron Petrusha <[email protected]> * Fixed malformed XML * fixed bad paramref * Update Utf8JsonReader.xml * Update Utf8JsonWriter.xml * Update Utf8JsonWriter.xml * Update Utf8JsonWriter.xml * Update Utf8JsonWriter.xml * Fixed broken xref. * suggestions by ahsonkhan Co-Authored-By: Ahson Khan <[email protected]> * suggestion by ahsonkhan for TryGetBytesFromBase64 * suggestions by ahsonkhan and bartonjs Co-Authored-By: Jeremy Barton <[email protected]> Co-Authored-By: Ahson Khan <[email protected]> * Bold JSON literals * smaller exception for Utf8JsonReader.GetBytesFromBase64 * suggestions by ahsonkhan Co-Authored-By: Ahson Khan <[email protected]> * JSON literal null for WriteNullValue * Changed type name * Corrected enum type name * Fixed bad cref * JSON literals * Fixed broken links * Fixed broken link
1 parent 987bce8 commit a758205

11 files changed

+972
-363
lines changed

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

Lines changed: 3 additions & 3 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>Provides the base class for serialization attributes.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -31,9 +31,9 @@
3131
</AssemblyInfo>
3232
<Parameters />
3333
<Docs>
34-
<summary>To be added.</summary>
34+
<summary>Creates a new instance of the <see cref="T:System.Text.Json.Serialization.JsonAttribute" />.</summary>
3535
<remarks>To be added.</remarks>
3636
</Docs>
3737
</Member>
3838
</Members>
39-
</Type>
39+
</Type>

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

Lines changed: 20 additions & 4 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 dictionary's `TKey` value must be <xref:System.String>, and `TValue` must be <xref:System.Text.Json.JsonElement> or <xref:System.Object>.
30+
31+
During deserialization, 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?displayProperty=nameWithType>.
32+
33+
During serialization, 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 property on a type with this extension data attribute, or if the property itself is not of the correct <see cref="T:System.Collections.Generic.IDictionary`2" /> 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">
@@ -36,9 +52,9 @@
3652
</AssemblyInfo>
3753
<Parameters />
3854
<Docs>
39-
<summary>To be added.</summary>
55+
<summary>Instantiates a new instance of the <see cref="T:System.Text.Json.Serialization.JsonExtensionDataAttribute" /> class.</summary>
4056
<remarks>To be added.</remarks>
4157
</Docs>
4258
</Member>
4359
</Members>
44-
</Type>
60+
</Type>

‎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: 6 additions & 6 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,10 +60,10 @@
6060
<ReturnType>System.String</ReturnType>
6161
</ReturnValue>
6262
<Docs>
63-
<summary>To be added.</summary>
64-
<value>To be added.</value>
63+
<summary>Gets the name of the property.</summary>
64+
<value>The name of the property.</value>
6565
<remarks>To be added.</remarks>
6666
</Docs>
6767
</Member>
6868
</Members>
69-
</Type>
69+
</Type>

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

Lines changed: 96 additions & 72 deletions
Large diffs are not rendered by default.

‎xml/System.Text.Json/JsonEncodedText.xml

Lines changed: 79 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,18 @@
2323
</Attribute>
2424
</Attributes>
2525
<Docs>
26-
<summary>To be added.</summary>
27-
<remarks>To be added.</remarks>
26+
<summary>Provides methods to transform UTF-8 or UTF-16 encoded text into a form that is suitable for JSON.</summary>
27+
<remarks>
28+
<format type="text/markdown">
29+
<![CDATA[
30+
31+
## Remarks
32+
33+
This type can be used to cache and store known strings used for writing JSON ahead of time by pre-encoding them up front.
34+
35+
]]>
36+
</format>
37+
</remarks>
2838
</Docs>
2939
<Members>
3040
<Member MemberName="Encode">
@@ -46,10 +56,11 @@
4656
<Parameter Name="utf8Value" Type="System.ReadOnlySpan&lt;System.Byte&gt;" />
4757
</Parameters>
4858
<Docs>
49-
<param name="utf8Value">To be added.</param>
50-
<summary>To be added.</summary>
51-
<returns>To be added.</returns>
59+
<param name="utf8Value">The UTF-8 encoded value to be transformed as JSON encoded text.</param>
60+
<summary>Encodes a UTF-8 encoded byte span as a JSON string.</summary>
61+
<returns>The JSON string.</returns>
5262
<remarks>To be added.</remarks>
63+
<exception cref="T:System.ArgumentException"><paramref name="utf8Value" /> is too large or contains invalid UTF-8 bytes.</exception>
5364
</Docs>
5465
</Member>
5566
<Member MemberName="Encode">
@@ -71,10 +82,11 @@
7182
<Parameter Name="value" Type="System.ReadOnlySpan&lt;System.Char&gt;" />
7283
</Parameters>
7384
<Docs>
74-
<param name="value">To be added.</param>
75-
<summary>To be added.</summary>
76-
<returns>To be added.</returns>
85+
<param name="value">The value to be transformed as JSON encoded text.</param>
86+
<summary>Encodes a UTF-16 encoded character span as a JSON string.</summary>
87+
<returns>The JSON string.</returns>
7788
<remarks>To be added.</remarks>
89+
<exception cref="T:System.ArgumentException"><paramref name="value" /> is too large or contains invalid UTF-16 characters.</exception>
7890
</Docs>
7991
</Member>
8092
<Member MemberName="Encode">
@@ -96,10 +108,12 @@
96108
<Parameter Name="value" Type="System.String" />
97109
</Parameters>
98110
<Docs>
99-
<param name="value">To be added.</param>
100-
<summary>To be added.</summary>
111+
<param name="value">The value to be transformed as JSON encoded text.</param>
112+
<summary>Encodes the string text value as a JSON string.</summary>
101113
<returns>To be added.</returns>
102114
<remarks>To be added.</remarks>
115+
<exception cref="T:System.ArgumentNullException"><paramref name="value" /> is <see langword="null" />.</exception>
116+
<exception cref="T:System.ArgumentException"><paramref name="value" /> is too large or contains invalid UTF-16 characters.</exception>
103117
</Docs>
104118
</Member>
105119
<Member MemberName="EncodedUtf8Bytes">
@@ -118,8 +132,8 @@
118132
<ReturnType>System.ReadOnlySpan&lt;System.Byte&gt;</ReturnType>
119133
</ReturnValue>
120134
<Docs>
121-
<summary>To be added.</summary>
122-
<value>To be added.</value>
135+
<summary>Gets the UTF-8 encoded representation of the pre-encoded JSON text.</summary>
136+
<value>The UTF-8 encoded representation of the pre-encoded JSON text.</value>
123137
<remarks>To be added.</remarks>
124138
</Docs>
125139
</Member>
@@ -143,9 +157,19 @@
143157
</Parameters>
144158
<Docs>
145159
<param name="obj">To be added.</param>
146-
<summary>To be added.</summary>
147-
<returns>To be added.</returns>
148-
<remarks>To be added.</remarks>
160+
<summary>Determines whether this instance and a specified object, which must also be a <see cref="T:System.Text.Json.JsonEncodedText" /> instance, have the same value.</summary>
161+
<returns><see langword="true" /> if the current instance and <paramref name="obj" /> are equal; otherwise, <see langword="false" />.</returns>
162+
<remarks>
163+
<format type="text/markdown">
164+
<![CDATA[
165+
166+
## Remarks
167+
168+
If `obj` is `null`, the method returns `false`.
169+
170+
]]>
171+
</format>
172+
</remarks>
149173
</Docs>
150174
</Member>
151175
<Member MemberName="Equals">
@@ -171,9 +195,19 @@
171195
</Parameters>
172196
<Docs>
173197
<param name="other">To be added.</param>
174-
<summary>To be added.</summary>
175-
<returns>To be added.</returns>
176-
<remarks>To be added.</remarks>
198+
<summary>Determines whether this instance and another specified <see cref="T:System.Text.Json.JsonEncodedText" /> instance have the same value.</summary>
199+
<returns><see langword="true" /> if this instance and <paramref name="other" /> have the same value; otherwise, <see langword="false" />.</returns>
200+
<remarks>
201+
<format type="text/markdown">
202+
<![CDATA[
203+
204+
## Remarks
205+
206+
Default instances of <xref:System.Text.Json.JsonEncodedText> are treated as equal.
207+
208+
]]>
209+
</format>
210+
</remarks>
177211
</Docs>
178212
</Member>
179213
<Member MemberName="GetHashCode">
@@ -193,9 +227,19 @@
193227
</ReturnValue>
194228
<Parameters />
195229
<Docs>
196-
<summary>To be added.</summary>
197-
<returns>To be added.</returns>
198-
<remarks>To be added.</remarks>
230+
<summary>Returns the hash code for this <see cref="T:System.Text.Json.JsonEncodedText" />.</summary>
231+
<returns>The hash code for this instance.</returns>
232+
<remarks>
233+
<format type="text/markdown">
234+
<![CDATA[
235+
236+
## Remarks
237+
238+
This method returns 0 on a default instance of <xref:System.Text.Json.JsonEncodedText>.
239+
240+
]]>
241+
</format>
242+
</remarks>
199243
</Docs>
200244
</Member>
201245
<Member MemberName="ToString">
@@ -215,10 +259,20 @@
215259
</ReturnValue>
216260
<Parameters />
217261
<Docs>
218-
<summary>To be added.</summary>
219-
<returns>To be added.</returns>
220-
<remarks>To be added.</remarks>
262+
<summary>Converts the value of this instance to a <see cref="T:System.String" />.</summary>
263+
<returns>The underlying UTF-16 encoded string.</returns>
264+
<remarks>
265+
<format type="text/markdown">
266+
<![CDATA[
267+
268+
## Remarks
269+
270+
This method returns an empty string on a default instance of <xref:System.Text.Json.JsonEncodedText>.
271+
272+
]]>
273+
</format>
274+
</remarks>
221275
</Docs>
222276
</Member>
223277
</Members>
224-
</Type>
278+
</Type>

0 commit comments

Comments
 (0)