|
18 | 18 | </Interface>
|
19 | 19 | </Interfaces>
|
20 | 20 | <Docs>
|
21 |
| - <summary>To be added.</summary> |
22 |
| - <remarks>To be added.</remarks> |
| 21 | + <summary>Provides a mechanism for examining the structural content of a JSON value without automatically instantiating data values.</summary> |
| 22 | + <remarks> |
| 23 | + <format><![CDATA[ |
| 24 | + |
| 25 | +This class utilizes resources from pooled memory to minimize the impact of the garbage collector (GC) in high-usage scenarios. Failure to properly dispose this object will result in the memory not being returned to the pool, which will increase GC impact across various parts of the framework. |
| 26 | + |
| 27 | + ]]></format> |
| 28 | + </remarks> |
23 | 29 | </Docs>
|
24 | 30 | <Members>
|
25 | 31 | <Member MemberName="Dispose">
|
|
65 | 71 | <Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
|
66 | 72 | </Parameters>
|
67 | 73 | <Docs>
|
68 |
| - <param name="utf8Json">To be added.</param> |
69 |
| - <param name="readerOptions">To be added.</param> |
70 |
| - <summary>To be added.</summary> |
71 |
| - <returns>To be added.</returns> |
72 |
| - <remarks>To be added.</remarks> |
| 74 | + <param name="utf8Json">The JSON text to parse.</param> |
| 75 | + <param name="readerOptions">Options to control the reader behavior during parsing.</param> |
| 76 | + <summary>Parses a sequence as UTF-8-encoded text representing a single JSON byte value into a JsonDocument.</summary> |
| 77 | + <returns>A JsonDocument representation of the JSON value.</returns> |
| 78 | + <remarks> |
| 79 | + <format><![CDATA[ |
| 80 | + |
| 81 | +The <xref:T:System.Buffers.ReadOnlySequence`1> may be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime. |
| 82 | + |
| 83 | +Because the input is considered to be text, a UTF-8 Byte-Order-Mark (BOM) must not be present. |
| 84 | +
|
| 85 | + ]]></format> |
| 86 | + </remarks> |
| 87 | + <exception cref="T:System.Text.Json.JsonException"> |
| 88 | + <paramref name="utf8Json" /> does not represent a valid single JSON value. |
| 89 | + </exception> |
| 90 | + <exception cref="T:System.ArgumentException"> |
| 91 | + <paramref name="readerOptions" /> contains unsupported options. |
| 92 | + </exception> |
73 | 93 | </Docs>
|
74 | 94 | </Member>
|
75 | 95 | <Member MemberName="Parse">
|
|
91 | 111 | <Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
|
92 | 112 | </Parameters>
|
93 | 113 | <Docs>
|
94 |
| - <param name="utf8Json">To be added.</param> |
95 |
| - <param name="readerOptions">To be added.</param> |
96 |
| - <summary>To be added.</summary> |
97 |
| - <returns>To be added.</returns> |
| 114 | + <param name="utf8Json">The JSON data to parse.</param> |
| 115 | + <param name="readerOptions">Options to control the reader behavior during parsing.</param> |
| 116 | + <summary>Parses a <see cref="T:System.IO.Stream" /> as UTF-8-encoded data representing a single JSON value into a JsonDocument. The stream is read to completion.</summary> |
| 117 | + <returns>A JsonDocument representation of the JSON value.</returns> |
98 | 118 | <remarks>To be added.</remarks>
|
| 119 | + <exception cref="T:System.Text.Json.JsonException"> |
| 120 | + <paramref name="utf8Json" /> does not represent a valid single JSON value. |
| 121 | + </exception> |
| 122 | + <exception cref="T:System.ArgumentException"> |
| 123 | + <paramref name="readerOptions" /> contains unsupported options. |
| 124 | + </exception> |
99 | 125 | </Docs>
|
100 | 126 | </Member>
|
101 | 127 | <Member MemberName="Parse">
|
|
117 | 143 | <Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
|
118 | 144 | </Parameters>
|
119 | 145 | <Docs>
|
120 |
| - <param name="utf8Json">To be added.</param> |
121 |
| - <param name="readerOptions">To be added.</param> |
122 |
| - <summary>To be added.</summary> |
123 |
| - <returns>To be added.</returns> |
124 |
| - <remarks>To be added.</remarks> |
| 146 | + <param name="utf8Json">The JSON text to parse.</param> |
| 147 | + <param name="readerOptions">Options to control the reader behavior during parsing.</param> |
| 148 | + <summary>Parses memory as UTF-8-encoded text representing a single JSON byte value into a JsonDocument.</summary> |
| 149 | + <returns>A JsonDocument representation of the JSON value.</returns> |
| 150 | + <remarks> |
| 151 | + <format><![CDATA[ |
| 152 | +
|
| 153 | +The <xref:T:System.ReadOnlyMemory`1> value will be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime. |
| 154 | +
|
| 155 | +Because the input is considered to be text, a UTF-8 Byte-Order-Mark (BOM) must not be present. |
| 156 | + |
| 157 | + ]]></format> |
| 158 | + </remarks> |
| 159 | + <exception cref="T:System.Text.Json.JsonException"> |
| 160 | + <paramref name="utf8Json" /> does not represent a valid single JSON value. |
| 161 | + </exception> |
| 162 | + <exception cref="T:System.ArgumentException"> |
| 163 | + <paramref name="readerOptions" /> contains unsupported options. |
| 164 | + </exception> |
125 | 165 | </Docs>
|
126 | 166 | </Member>
|
127 | 167 | <Member MemberName="Parse">
|
|
143 | 183 | <Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
|
144 | 184 | </Parameters>
|
145 | 185 | <Docs>
|
146 |
| - <param name="json">To be added.</param> |
147 |
| - <param name="readerOptions">To be added.</param> |
148 |
| - <summary>To be added.</summary> |
149 |
| - <returns>To be added.</returns> |
150 |
| - <remarks>To be added.</remarks> |
| 186 | + <param name="json">The JSON text to parse.</param> |
| 187 | + <param name="readerOptions">Options to control the reader behavior during parsing.</param> |
| 188 | + <summary>Parses text representing a single JSON character value into a JsonDocument.</summary> |
| 189 | + <returns>A JsonDocument representation of the JSON value.</returns> |
| 190 | + <remarks> |
| 191 | + <format><![CDATA[ |
| 192 | + |
| 193 | +The <xref:T:System.ReadOnlyMemory`1> value may be used for the entire lifetime of the JsonDocument object, and the caller must ensure that the data therein does not change during the object lifetime. |
| 194 | +
|
| 195 | + ]]></format> |
| 196 | + </remarks> |
| 197 | + <exception cref="T:System.Text.Json.JsonException"> |
| 198 | + <paramref name="json" /> does not represent a valid single JSON value. |
| 199 | + </exception> |
| 200 | + <exception cref="T:System.ArgumentException"> |
| 201 | + <paramref name="readerOptions" /> contains unsupported options. |
| 202 | + </exception> |
151 | 203 | </Docs>
|
152 | 204 | </Member>
|
153 | 205 | <Member MemberName="Parse">
|
|
169 | 221 | <Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
|
170 | 222 | </Parameters>
|
171 | 223 | <Docs>
|
172 |
| - <param name="json">To be added.</param> |
173 |
| - <param name="readerOptions">To be added.</param> |
174 |
| - <summary>To be added.</summary> |
175 |
| - <returns>To be added.</returns> |
| 224 | + <param name="json">The JSON text to parse.</param> |
| 225 | + <param name="readerOptions">Options to control the reader behavior during parsing.</param> |
| 226 | + <summary>Parses text representing a single JSON string value into a JsonDocument.</summary> |
| 227 | + <returns>A JsonDocument representation of the JSON value.</returns> |
176 | 228 | <remarks>To be added.</remarks>
|
| 229 | + <exception cref="T:System.Text.Json.JsonException"> |
| 230 | + <paramref name="json" /> does not represent a valid single JSON value. |
| 231 | + </exception> |
| 232 | + <exception cref="T:System.ArgumentException"> |
| 233 | + <paramref name="readerOptions" /> contains unsupported options. |
| 234 | + </exception> |
177 | 235 | </Docs>
|
178 | 236 | </Member>
|
179 | 237 | <Member MemberName="ParseAsync">
|
|
195 | 253 | <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
|
196 | 254 | </Parameters>
|
197 | 255 | <Docs>
|
198 |
| - <param name="utf8Json">To be added.</param> |
199 |
| - <param name="readerOptions">To be added.</param> |
200 |
| - <param name="cancellationToken">To be added.</param> |
201 |
| - <summary>To be added.</summary> |
202 |
| - <returns>To be added.</returns> |
| 256 | + <param name="utf8Json">The JSON data to parse.</param> |
| 257 | + <param name="readerOptions">Options to control the reader behavior during parsing.</param> |
| 258 | + <param name="cancellationToken">The token to monitor for cancellation requests.</param> |
| 259 | + <summary>Parses a <see cref="T:System.IO.Stream" /> as UTF-8-encoded data representing a single JSON value into a JsonDocument. The stream is read to completion.</summary> |
| 260 | + <returns>A task to produce a JsonDocument representation of the JSON value.</returns> |
203 | 261 | <remarks>To be added.</remarks>
|
| 262 | + <exception cref="T:System.Text.Json.JsonException"> |
| 263 | + <paramref name="utf8Json" /> does not represent a valid single JSON value. |
| 264 | + </exception> |
| 265 | + <exception cref="T:System.ArgumentException"> |
| 266 | + <paramref name="readerOptions" /> contains unsupported options. |
| 267 | + </exception> |
204 | 268 | </Docs>
|
205 | 269 | </Member>
|
206 | 270 | <Member MemberName="ParseValue">
|
|
222 | 286 | <Parameter Name="reader" Type="System.Text.Json.Utf8JsonReader" RefType="ref" />
|
223 | 287 | </Parameters>
|
224 | 288 | <Docs>
|
225 |
| - <param name="reader">To be added.</param> |
226 |
| - <summary>To be added.</summary> |
227 |
| - <returns>To be added.</returns> |
228 |
| - <remarks>To be added.</remarks> |
| 289 | + <param name="reader">The reader to read.</param> |
| 290 | + <summary>Parses one JSON value (including objects or arrays) from the provided reader.</summary> |
| 291 | + <returns>A JsonDocument representing the value (and nested values) read from the reader.</returns> |
| 292 | + <remarks> |
| 293 | + <format><![CDATA[ |
| 294 | +
|
| 295 | +If the <xref:System.Text.Json.Utf8JsonReader.TokenType> property of `reader` is <xref:System.Text.Json.JsonTokenType.PropertyName> or <xref:System.Text.Json.JsonTokenType.None?displayProperty=nameWithType>, the reader will advance by one call to <xref:System.Text.Json.Utf8JsonReader.Read?displayProperty=nameWithType> to determine the start of the value. |
| 296 | + |
| 297 | +Upon completion of this method, `reader` is positioned at the final token in the JSON value. If an exception is thrown, the reader is reset to |
| 298 | +the state it was in when the method was called. |
| 299 | + |
| 300 | +This method makes a copy of the data the reader acted on, so there is no caller requirement to maintain data integrity beyond the return of this method. |
| 301 | +
|
| 302 | + ]]></format> |
| 303 | + </remarks> |
| 304 | + <exception cref="T:System.ArgumentException"> |
| 305 | + <paramref name="reader" /> contains unsupported options. |
| 306 | + </exception> |
| 307 | + <exception cref="T:System.Text.Json.JsonException"> |
| 308 | + A value could not be read from the reader. |
| 309 | + </exception> |
229 | 310 | </Docs>
|
230 | 311 | </Member>
|
231 | 312 | <Member MemberName="RootElement">
|
|
244 | 325 | <ReturnType>System.Text.Json.JsonElement</ReturnType>
|
245 | 326 | </ReturnValue>
|
246 | 327 | <Docs>
|
247 |
| - <summary>To be added.</summary> |
| 328 | + <summary>Gets the root element of this JSON document.</summary> |
248 | 329 | <value>To be added.</value>
|
249 | 330 | <remarks>To be added.</remarks>
|
250 | 331 | </Docs>
|
|
269 | 350 | <Parameter Name="document" Type="System.Text.Json.JsonDocument" RefType="out" />
|
270 | 351 | </Parameters>
|
271 | 352 | <Docs>
|
272 |
| - <param name="reader">To be added.</param> |
273 |
| - <param name="document">To be added.</param> |
274 |
| - <summary>To be added.</summary> |
275 |
| - <returns>To be added.</returns> |
276 |
| - <remarks>To be added.</remarks> |
| 353 | + <param name="reader">The reader to read.</param> |
| 354 | + <param name="document">When the method returns, contains the parsed document.</param> |
| 355 | + <summary>Attempts to parse one JSON value (including objects or arrays) from the provided reader.</summary> |
| 356 | + <returns> |
| 357 | + <see langword="true" /> if a value was read and parsed into a JsonDocument; <see langword="false" /> if the reader ran out of data while parsing. All other situations result in an exception being thrown.</returns> |
| 358 | + <remarks> |
| 359 | + <format><![CDATA[ |
| 360 | + |
| 361 | +If the <xref:System.Text.Json.Utf8JsonReader.TokenType> property of `reader` is <xref:System.Text.Json.JsonTokenType.PropertyName?displayProperty=nameWithType> or <xref:System.Text.Json.JsonTokenType.None?displayProperty=nameWithType>, the reader will advance by one call to <xref:System.Text.Json.Utf8JsonReader.Read?displayProperty=nameWithType> to determine the start of the value. |
| 362 | + |
| 363 | +Upon completion of this method, `reader` is positioned at the final token in the JSON value. If an exception is thrown or `false` |
| 364 | +is returned, the reader is reset to the state it was in when the method was called. |
| 365 | + |
| 366 | +This method makes a copy of the data the reader acted on, so there is no caller requirement to maintain data integrity beyond the return of this method. |
| 367 | + |
| 368 | + ]]></format> |
| 369 | + </remarks> |
| 370 | + <exception cref="T:System.ArgumentException"> |
| 371 | + <paramref name="reader" /> contains unsupported options. |
| 372 | + </exception> |
| 373 | + <exception cref="T:System.Text.Json.JsonException"> |
| 374 | + A value could not be read from the reader. |
| 375 | + </exception> |
277 | 376 | </Docs>
|
278 | 377 | </Member>
|
279 | 378 | </Members>
|
|
0 commit comments