Skip to content

Commit 31b8fe9

Browse files
mairawmairaw
authored
add content for System.Text.Json APIs (#1880)
* add content for System.Text.Json from /// comments * edit pass + formatting * save interim changes * feedback * last edits * Apply suggestions from peer review Co-Authored-By: mairaw <[email protected]> * feedback
1 parent 7882b09 commit 31b8fe9

9 files changed

+1174
-433
lines changed

‎xml/System.Text.Json/JsonCommentHandling.xml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
<BaseTypeName>System.Enum</BaseTypeName>
1414
</Base>
1515
<Docs>
16-
<summary>To be added.</summary>
16+
<summary>Defines how the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct handles comments.</summary>
1717
<remarks>To be added.</remarks>
1818
</Docs>
1919
<Members>
@@ -34,7 +34,7 @@
3434
</ReturnValue>
3535
<MemberValue>1</MemberValue>
3636
<Docs>
37-
<summary>To be added.</summary>
37+
<summary>Allows comments within the JSON input and treats them as valid tokens. While reading, the caller can to access the comment values.</summary>
3838
</Docs>
3939
</Member>
4040
<Member MemberName="Disallow">
@@ -54,7 +54,7 @@
5454
</ReturnValue>
5555
<MemberValue>0</MemberValue>
5656
<Docs>
57-
<summary>To be added.</summary>
57+
<summary>Doesn't allow comments within the JSON input. Comments are treated as invalid JSON if found, and a <see cref="T:System.Text.Json.JsonReaderException" /> is thrown. This is the default value.</summary>
5858
</Docs>
5959
</Member>
6060
<Member MemberName="Skip">
@@ -74,8 +74,8 @@
7474
</ReturnValue>
7575
<MemberValue>2</MemberValue>
7676
<Docs>
77-
<summary>To be added.</summary>
77+
<summary>Allows comments within the JSON input and ignores them. The <see cref="T:System.Text.Json.Utf8JsonReader" /> behaves as if no comments are present.</summary>
7878
</Docs>
7979
</Member>
8080
</Members>
81-
</Type>
81+
</Type>

‎xml/System.Text.Json/JsonReaderException.xml‎

Lines changed: 22 additions & 14 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 exception that is thrown when <see cref="T:System.Text.Json.Utf8JsonReader" /> encounters invalid data or data disallowed by any of its options.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -36,11 +36,19 @@
3636
<Parameter Name="bytePositionInLine" Type="System.Int64" />
3737
</Parameters>
3838
<Docs>
39-
<param name="message">To be added.</param>
40-
<param name="lineNumber">To be added.</param>
41-
<param name="bytePositionInLine">To be added.</param>
42-
<summary>To be added.</summary>
43-
<remarks>To be added.</remarks>
39+
<param name="message">The context-specific error message.</param>
40+
<param name="lineNumber">The line number (starting at 0) at which the invalid JSON was encountered.</param>
41+
<param name="bytePositionInLine">The byte count (starting at 0) in the current line where the invalid JSON was encountered.</param>
42+
<summary>Creates a new exception object to relay error information to the user.</summary>
43+
<remarks>
44+
<format type="text/markdown"><![CDATA[
45+
46+
## Remarks
47+
48+
Note that the `bytePositionInLine` counts the number of bytes (that is, UTF-8 code units) and not characters or scalars.
49+
50+
]]></format>
51+
</remarks>
4452
</Docs>
4553
</Member>
4654
<Member MemberName="BytePositionInLine">
@@ -59,8 +67,8 @@
5967
<ReturnType>System.Int64</ReturnType>
6068
</ReturnValue>
6169
<Docs>
62-
<summary>To be added.</summary>
63-
<value>To be added.</value>
70+
<summary>Gets the number of bytes read within the current line (starting at 0) before the exception.</summary>
71+
<value>The number of bytes read within the current line (starting at 0) before the exception.</value>
6472
<remarks>To be added.</remarks>
6573
</Docs>
6674
</Member>
@@ -84,9 +92,9 @@
8492
<Parameter Name="context" Type="System.Runtime.Serialization.StreamingContext" />
8593
</Parameters>
8694
<Docs>
87-
<param name="info">To be added.</param>
88-
<param name="context">To be added.</param>
89-
<summary>To be added.</summary>
95+
<param name="info">The <see cref="T:System.Runtime.Serialization.SerializationInfo" /> that holds the serialized object data about the exception being thrown.</param>
96+
<param name="context">The <see cref="T:System.Runtime.Serialization.StreamingContext" /> that contains contextual information about the source or destination.</param>
97+
<summary>Sets the <see cref="T:System.Runtime.Serialization.SerializationInfo" /> with information about the exception.</summary>
9098
<remarks>To be added.</remarks>
9199
</Docs>
92100
</Member>
@@ -106,10 +114,10 @@
106114
<ReturnType>System.Int64</ReturnType>
107115
</ReturnValue>
108116
<Docs>
109-
<summary>To be added.</summary>
110-
<value>To be added.</value>
117+
<summary>Gets the number of lines read (starting at 0) before the exception.</summary>
118+
<value>The number of lines read (starting at 0) before the exception.</value>
111119
<remarks>To be added.</remarks>
112120
</Docs>
113121
</Member>
114122
</Members>
115-
</Type>
123+
</Type>

‎xml/System.Text.Json/JsonReaderOptions.xml‎

Lines changed: 12 additions & 4 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 ability for the user to define custom behavior when reading JSON.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -34,9 +34,17 @@
3434
<ReturnType>System.Text.Json.JsonCommentHandling</ReturnType>
3535
</ReturnValue>
3636
<Docs>
37-
<summary>To be added.</summary>
38-
<value>To be added.</value>
39-
<remarks>To be added.</remarks>
37+
<summary>Gets or sets how the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct handles comments when reading through the JSON data.</summary>
38+
<value>One of the enumeration values that indicates how comments are handled.</value>
39+
<remarks>
40+
<format type="text/markdown"><![CDATA[
41+
42+
## Remarks
43+
44+
By default, the reader throws a <xref:System.Text.Json.JsonReaderException> if it encounters a comment.
45+
46+
]]></format>
47+
</remarks>
4048
</Docs>
4149
</Member>
4250
</Members>

‎xml/System.Text.Json/JsonReaderState.xml‎

Lines changed: 46 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,18 @@
1414
</Base>
1515
<Interfaces />
1616
<Docs>
17-
<summary>To be added.</summary>
18-
<remarks>To be added.</remarks>
17+
<summary>Defines an opaque type that holds and saves all the relevant state information, which must be provided to the <see cref="T:System.Text.Json.Utf8JsonReader" /> to continue reading after processing incomplete data.</summary>
18+
<remarks>
19+
<format type="text/markdown"><![CDATA[
20+
21+
## Remarks
22+
23+
`JsonReaderState` is required to support reentrancy when reading incomplete data, and to continue reading once more data is available.
24+
Unlike the <xref:System.Text.Json.Utf8JsonReader> struct, which is a ref struct,
25+
this type can survive across async/await boundaries, and hence it's required to provide support for reading more data asynchronously before continuing with a new instance of the <xref:System.Text.Json.Utf8JsonReader>.
26+
27+
]]></format>
28+
</remarks>
1929
</Docs>
2030
<Members>
2131
<Member MemberName=".ctor">
@@ -34,10 +44,22 @@
3444
<Parameter Name="options" Type="System.Text.Json.JsonReaderOptions" />
3545
</Parameters>
3646
<Docs>
37-
<param name="maxDepth">To be added.</param>
38-
<param name="options">To be added.</param>
39-
<summary>To be added.</summary>
40-
<remarks>To be added.</remarks>
47+
<param name="maxDepth">The maximum depth allowed when reading JSON. This is an optional parameter, and its default value is 64. Reading past this depth throws a <see cref="T:System.Text.Json.JsonReaderException" /></param>
48+
<param name="options">The customized behavior of the <see cref="T:System.Text.Json.Utf8JsonReader" /> that is different from the JSON RFC (for example, how to handle comments).
49+
This is an optional parameter and, by default, the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct follows the JSON RFC strictly (that is, comments within the JSON are invalid).</param>
50+
<summary>Initializes a new instance of the <see cref="T:System.Text.Json.JsonReaderState" /> struct.</summary>
51+
<remarks>
52+
<format type="text/markdown"><![CDATA[
53+
54+
## Remarks
55+
56+
A <xref:System.Text.Json.JsonReaderState> instance must be passed to the <xref:System.Text.Json.Utf8JsonReader> constructor with the JSON data.
57+
Unlike the <xref:System.Text.Json.Utf8JsonReader>, which is a ref struct, the state can survive across async/await boundaries, and hence this type is required to provide support for reading more data asynchronously before continuing with a new instance of the <xref:System.Text.Json.Utf8JsonReader> class.
58+
59+
]]></format>
60+
</remarks>
61+
<exception cref="T:System.ArgumentException">
62+
<paramref name="maxDepth" /> is less than or equal to 0.</exception>
4163
</Docs>
4264
</Member>
4365
<Member MemberName="BytesConsumed">
@@ -56,8 +78,8 @@
5678
<ReturnType>System.Int64</ReturnType>
5779
</ReturnValue>
5880
<Docs>
59-
<summary>To be added.</summary>
60-
<value>To be added.</value>
81+
<summary>Gets the total number of bytes consumed by the <see cref="T:System.Text.Json.Utf8JsonReader" /> so far for the given UTF-8 encoded input text.</summary>
82+
<value>The total number of bytes consumed by the <see cref="T:System.Text.Json.Utf8JsonReader" /> so far.</value>
6183
<remarks>To be added.</remarks>
6284
</Docs>
6385
</Member>
@@ -77,9 +99,17 @@
7799
<ReturnType>System.Int32</ReturnType>
78100
</ReturnValue>
79101
<Docs>
80-
<summary>To be added.</summary>
102+
<summary>Gets the maximum depth allowed when reading JSON.</summary>
81103
<value>To be added.</value>
82-
<remarks>To be added.</remarks>
104+
<remarks>
105+
<format type="text/markdown"><![CDATA[
106+
107+
## Remarks
108+
109+
Reading past `MaxDepth` throws a <xref:System.Text.Json.JsonReaderException>.
110+
111+
]]></format>
112+
</remarks>
83113
</Docs>
84114
</Member>
85115
<Member MemberName="Options">
@@ -98,8 +128,8 @@
98128
<ReturnType>System.Text.Json.JsonReaderOptions</ReturnType>
99129
</ReturnValue>
100130
<Docs>
101-
<summary>To be added.</summary>
102-
<value>To be added.</value>
131+
<summary>Gets the custom behavior to use when reading JSON data using the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct that may deviate from strict adherence to the JSON specification, which is the default behavior.</summary>
132+
<value>The custom behavior to use when reading JSON data.</value>
103133
<remarks>To be added.</remarks>
104134
</Docs>
105135
</Member>
@@ -119,10 +149,11 @@
119149
<ReturnType>System.SequencePosition</ReturnType>
120150
</ReturnValue>
121151
<Docs>
122-
<summary>To be added.</summary>
123-
<value>To be added.</value>
152+
<summary>Gets the current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt;. If the <see cref="T:System.Text.Json.Utf8JsonReader" /> struct was constructed
153+
with a ReadOnlySpan&lt;byte&gt; instead, this will always return a default <see cref="T:System.SequencePosition" />.</summary>
154+
<value>The current <see cref="T:System.SequencePosition" /> within the provided UTF-8 encoded input ReadOnlySequence&lt;byte&gt;.</value>
124155
<remarks>To be added.</remarks>
125156
</Docs>
126157
</Member>
127158
</Members>
128-
</Type>
159+
</Type>

‎xml/System.Text.Json/JsonTokenType.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
<BaseTypeName>System.Enum</BaseTypeName>
1414
</Base>
1515
<Docs>
16-
<summary>To be added.</summary>
16+
<summary>Defines the various JSON tokens that make up a JSON text.</summary>
1717
<remarks>To be added.</remarks>
1818
</Docs>
1919
<Members>

‎xml/System.Text.Json/JsonWriterOptions.xml‎

Lines changed: 26 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,17 @@
1414
</Base>
1515
<Interfaces />
1616
<Docs>
17-
<summary>To be added.</summary>
18-
<remarks>To be added.</remarks>
17+
<summary>Allows the user to define custom behavior when writing JSON using the <see cref="T:System.Text.Json.Utf8JsonWriter" />.</summary>
18+
<remarks>
19+
<format type="text/markdown"><![CDATA[
20+
21+
## Remarks
22+
23+
By default, the JSON is written without any indentation or extra white space.
24+
Also, <xref:System.Text.Json.Utf8JsonWriter> throws an exception if the user attempts to write structurally invalid JSON.
25+
26+
]]></format>
27+
</remarks>
1928
</Docs>
2029
<Members>
2130
<Member MemberName="Indented">
@@ -34,8 +43,8 @@
3443
<ReturnType>System.Boolean</ReturnType>
3544
</ReturnValue>
3645
<Docs>
37-
<summary>To be added.</summary>
38-
<value>To be added.</value>
46+
<summary>Gets or sets a value that indicates whether the <see cref="T:System.Text.Json.Utf8JsonWriter" /> should format the JSON output, which includes indenting nested JSON tokens, adding new lines, and adding white space between property names and values.</summary>
47+
<value><see langword="true" /> to format the JSON output; <see langword="false" /> to write without any extra white space. The default is <see langword="false" />.</value>
3948
<remarks>To be added.</remarks>
4049
</Docs>
4150
</Member>
@@ -55,9 +64,19 @@
5564
<ReturnType>System.Boolean</ReturnType>
5665
</ReturnValue>
5766
<Docs>
58-
<summary>To be added.</summary>
59-
<value>To be added.</value>
60-
<remarks>To be added.</remarks>
67+
<summary>Gets or sets a value that indicates whether the <see cref="T:System.Text.Json.Utf8JsonWriter" /> should skip structural validation and allow the user to write invalid JSON.</summary>
68+
<value><see langword="true" /> to skip structural validation and allow invalid JSON; <see langword="false" /> to throw an <see cref="T:System.InvalidOperationException" /> on any attempt to write invalid JSON.
69+
</value>
70+
<remarks>
71+
<format type="text/markdown"><![CDATA[
72+
73+
## Remarks
74+
75+
If the JSON being written is known to be correct, then skipping validation (by setting this property to `true`) could improve performance.
76+
An example of invalid JSON where the writer will throw (when `SkipValidation` is set to `false`) is when you write a value within a JSON object without a property name.
77+
78+
]]></format>
79+
</remarks>
6180
</Docs>
6281
</Member>
6382
</Members>

‎xml/System.Text.Json/JsonWriterState.xml‎

Lines changed: 33 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,18 @@
1414
</Base>
1515
<Interfaces />
1616
<Docs>
17-
<summary>To be added.</summary>
18-
<remarks>To be added.</remarks>
17+
<summary>Defines an opaque type that holds and saves all the relevant state information which must be provided to the <see cref="T:System.Text.Json.Utf8JsonWriter" /> struct to continue writing after completing a partial write.</summary>
18+
<remarks>
19+
<format type="text/markdown"><![CDATA[
20+
21+
## Remarks
22+
23+
This type is required to support reentrancy when writing incomplete data and to continue writing in chunks.
24+
Unlike the <xref:System.Text.Json.Utf8JsonWriter" />, which is a ref struct,
25+
this type can survive across async/await boundaries, and hence this type is required to provide support for writing more JSON text asynchronously before continuing with a new instance of the <xref:System.Text.Json.Utf8JsonWriter>.
26+
27+
]]></format>
28+
</remarks>
1929
</Docs>
2030
<Members>
2131
<Member MemberName=".ctor">
@@ -33,9 +43,20 @@
3343
<Parameter Name="options" Type="System.Text.Json.JsonWriterOptions" />
3444
</Parameters>
3545
<Docs>
36-
<param name="options">To be added.</param>
37-
<summary>To be added.</summary>
38-
<remarks>To be added.</remarks>
46+
<param name="options">The customized behavior of the <see cref="T:System.Text.Json.Utf8JsonWriter" /> struct.
47+
By default, the <see cref="T:System.Text.Json.Utf8JsonWriter" /> writes JSON minimized (that is, with no extra white space) and validates that the JSON data being written is structurally valid according to JSON RFC.</param>
48+
<summary>Initializes a new instance of the <see cref="T:System.Text.Json.JsonWriterState" /> struct.</summary>
49+
<remarks>
50+
<format type="text/markdown"><![CDATA[
51+
52+
## Remarks
53+
54+
An instance of this state must be passed to the <xref:System.Text.Json.Utf8JsonWriter> constructor with the output destination.
55+
Unlike the <xref:System.Text.Json.Utf8JsonWriter>, which is a ref struct, the state can survive across async/await boundaries, and hence this type is required to provide support for reading
56+
more data asynchronously before continuing with a new instance of the <xref:System.Text.Json.Utf8JsonWriter> struct.
57+
58+
]]></format>
59+
</remarks>
3960
</Docs>
4061
</Member>
4162
<Member MemberName="BytesCommitted">
@@ -54,8 +75,8 @@
5475
<ReturnType>System.Int64</ReturnType>
5576
</ReturnValue>
5677
<Docs>
57-
<summary>To be added.</summary>
58-
<value>To be added.</value>
78+
<summary>Gets the total number of bytes committed to the output by the <see cref="T:System.Text.Json.Utf8JsonWriter" /> struct so far. This indicates how much the <see cref="T:System.Buffers.IBufferWriter`1" /> has advanced.</summary>
79+
<value>The total number of bytes committed to the output.</value>
5980
<remarks>To be added.</remarks>
6081
</Docs>
6182
</Member>
@@ -75,8 +96,8 @@
7596
<ReturnType>System.Int64</ReturnType>
7697
</ReturnValue>
7798
<Docs>
78-
<summary>To be added.</summary>
79-
<value>To be added.</value>
99+
<summary>Gets the total number of bytes written by the <see cref="T:System.Text.Json.Utf8JsonWriter" /> struct so far. This includes data that has been written beyond what has already been committed.</summary>
100+
<value>The total number of bytes written.</value>
80101
<remarks>To be added.</remarks>
81102
</Docs>
82103
</Member>
@@ -96,10 +117,10 @@
96117
<ReturnType>System.Text.Json.JsonWriterOptions</ReturnType>
97118
</ReturnValue>
98119
<Docs>
99-
<summary>To be added.</summary>
100-
<value>To be added.</value>
120+
<summary>Gets the custom behavior to use when writing JSON data using the <see cref="T:System.Text.Json.Utf8JsonWriter" /> struct.</summary>
121+
<value>The custom behavior to use when writing JSON data.</value>
101122
<remarks>To be added.</remarks>
102123
</Docs>
103124
</Member>
104125
</Members>
105-
</Type>
126+
</Type>

0 commit comments

Comments
 (0)