Skip to content

Commit eb207b8

Browse files
carlossanlopRon Petrusha
authored andcommitted
Port System.Text.Json source comments to Docs (second attempt) (#2471)
* Port System.Text.Json source code comments to Docs - second attempt with most up-to-date APIs. * Incorporated revisions * Additional change
1 parent 41b31a3 commit eb207b8

10 files changed

+1524
-582
lines changed

xml/System.Text.Json/JsonDocument.xml

Lines changed: 139 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,14 @@
1818
</Interface>
1919
</Interfaces>
2020
<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>
2329
</Docs>
2430
<Members>
2531
<Member MemberName="Dispose">
@@ -65,11 +71,25 @@
6571
<Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
6672
</Parameters>
6773
<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>
7393
</Docs>
7494
</Member>
7595
<Member MemberName="Parse">
@@ -91,11 +111,17 @@
91111
<Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
92112
</Parameters>
93113
<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>
98118
<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>
99125
</Docs>
100126
</Member>
101127
<Member MemberName="Parse">
@@ -117,11 +143,25 @@
117143
<Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
118144
</Parameters>
119145
<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>
125165
</Docs>
126166
</Member>
127167
<Member MemberName="Parse">
@@ -143,11 +183,23 @@
143183
<Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
144184
</Parameters>
145185
<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>
151203
</Docs>
152204
</Member>
153205
<Member MemberName="Parse">
@@ -169,11 +221,17 @@
169221
<Parameter Name="readerOptions" Type="System.Text.Json.JsonReaderOptions" />
170222
</Parameters>
171223
<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>
176228
<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>
177235
</Docs>
178236
</Member>
179237
<Member MemberName="ParseAsync">
@@ -195,12 +253,18 @@
195253
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
196254
</Parameters>
197255
<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>
203261
<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>
204268
</Docs>
205269
</Member>
206270
<Member MemberName="ParseValue">
@@ -222,10 +286,27 @@
222286
<Parameter Name="reader" Type="System.Text.Json.Utf8JsonReader" RefType="ref" />
223287
</Parameters>
224288
<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>
229310
</Docs>
230311
</Member>
231312
<Member MemberName="RootElement">
@@ -244,7 +325,7 @@
244325
<ReturnType>System.Text.Json.JsonElement</ReturnType>
245326
</ReturnValue>
246327
<Docs>
247-
<summary>To be added.</summary>
328+
<summary>Gets the root element of this JSON document.</summary>
248329
<value>To be added.</value>
249330
<remarks>To be added.</remarks>
250331
</Docs>
@@ -269,11 +350,29 @@
269350
<Parameter Name="document" Type="System.Text.Json.JsonDocument" RefType="out" />
270351
</Parameters>
271352
<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>
277376
</Docs>
278377
</Member>
279378
</Members>

xml/System.Text.Json/JsonElement+ArrayEnumerator.xml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
</Interface>
3131
</Interfaces>
3232
<Docs>
33-
<summary>To be added.</summary>
33+
<summary>Represents an enumerator for the contents of a JSON array.</summary>
3434
<remarks>To be added.</remarks>
3535
</Docs>
3636
<Members>
@@ -99,8 +99,8 @@
9999
</ReturnValue>
100100
<Parameters />
101101
<Docs>
102-
<summary>To be added.</summary>
103-
<returns>To be added.</returns>
102+
<summary>Returns an enumerator that iterates through a collection.</summary>
103+
<returns>An enumeratore that can be used to iterate through the array.</returns>
104104
<remarks>To be added.</remarks>
105105
</Docs>
106106
</Member>

xml/System.Text.Json/JsonElement+ObjectEnumerator.xml

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
</Interface>
3131
</Interfaces>
3232
<Docs>
33-
<summary>To be added.</summary>
33+
<summary>Represents an enumerator for the properties of a JSON object.</summary>
3434
<remarks>To be added.</remarks>
3535
</Docs>
3636
<Members>
@@ -99,9 +99,15 @@
9999
</ReturnValue>
100100
<Parameters />
101101
<Docs>
102-
<summary>To be added.</summary>
103-
<returns>To be added.</returns>
104-
<remarks>To be added.</remarks>
102+
<summary>Returns an enumerator that iterates the properties of an object.</summary>
103+
<returns>An enumerator that can be used to iterate through the object.</returns>
104+
<remarks>
105+
<format><![CDATA[
106+
107+
The enumerator will enumerate the properties in the order they are declared, and when an object has multiple definitions of a single property, they will all individually be returned (each in the order they appear in the content).
108+
109+
]]></format>
110+
</remarks>
105111
</Docs>
106112
</Member>
107113
<Member MemberName="MoveNext">

0 commit comments

Comments
 (0)