Skip to content

Commit 14faa42

Browse files
carlossanlopeiriktsarpalis
carlossanlop
and
eiriktsarpalis
authored
Port System.Text.Json new docs (#10206)
* System.Text.Json * System.Text.Json.Nodes * System.Text.Json.Schema * System.Text.Json.Serialization.Metadata * System.Text.Json.Serialization * Apply suggestion Co-authored-by: Eirik Tsarpalis <[email protected]> --------- Co-authored-by: Eirik Tsarpalis <[email protected]>
1 parent c7a2189 commit 14faa42

19 files changed

+308
-144
lines changed

‎xml/System.Text.Json.Nodes/JsonArray.xml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -118,8 +118,8 @@ It is safe to perform multiple concurrent read operations on a <xref:System.Text
118118
</Parameter>
119119
</Parameters>
120120
<Docs>
121-
<param name="items">To be added.</param>
122-
<summary>To be added.</summary>
121+
<param name="items">The items to add to the new <see cref="T:System.Text.Json.Nodes.JsonArray" />.</param>
122+
<summary>Initializes a new instance of the <see cref="T:System.Text.Json.Nodes.JsonArray" /> class that contains items from the specified span.</summary>
123123
<remarks>To be added.</remarks>
124124
</Docs>
125125
</Member>
@@ -188,9 +188,9 @@ It is safe to perform multiple concurrent read operations on a <xref:System.Text
188188
</Parameter>
189189
</Parameters>
190190
<Docs>
191-
<param name="options">To be added.</param>
192-
<param name="items">To be added.</param>
193-
<summary>To be added.</summary>
191+
<param name="options">Options to control the behavior.</param>
192+
<param name="items">The items to add to the new <see cref="T:System.Text.Json.Nodes.JsonArray" />.</param>
193+
<summary>Initializes a new instance of the <see cref="T:System.Text.Json.Nodes.JsonArray" /> class that contains items from the specified params span.</summary>
194194
<remarks>To be added.</remarks>
195195
</Docs>
196196
</Member>

‎xml/System.Text.Json.Nodes/JsonObject.xml

Lines changed: 40 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -348,10 +348,12 @@ It's safe to perform multiple concurrent read operations on a <xref:System.Text.
348348
<Parameter Name="index" Type="System.Int32" Index="0" FrameworkAlternate="net-8.0;net-9.0;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-2.0" />
349349
</Parameters>
350350
<Docs>
351-
<param name="index">To be added.</param>
352-
<summary>To be added.</summary>
353-
<returns>To be added.</returns>
351+
<param name="index">The zero-based index of the pair to get.</param>
352+
<summary>Gets the property of the specified index.</summary>
353+
<returns>The property at the specified index as a key/value pair.</returns>
354354
<remarks>To be added.</remarks>
355+
<exception cref="T:System.ArgumentOutOfRangeException">
356+
<paramref name="index" /> is less than 0 or greater than or equal to <see cref="P:System.Text.Json.Nodes.JsonObject.Count" />.</exception>
355357
</Docs>
356358
</Member>
357359
<Member MemberName="GetEnumerator">
@@ -399,10 +401,12 @@ It's safe to perform multiple concurrent read operations on a <xref:System.Text.
399401
<Parameter Name="propertyName" Type="System.String" Index="0" FrameworkAlternate="net-8.0;net-9.0;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-2.0" />
400402
</Parameters>
401403
<Docs>
402-
<param name="propertyName">To be added.</param>
403-
<summary>To be added.</summary>
404-
<returns>To be added.</returns>
404+
<param name="propertyName">The property name to locate.</param>
405+
<summary>Determines the index of a specific property name in the object.</summary>
406+
<returns>The index of <paramref name="propertyName" /> if found; otherwise, -1.</returns>
405407
<remarks>To be added.</remarks>
408+
<exception cref="T:System.ArgumentNullException">
409+
<paramref name="propertyName" /> is <see langword="null" />.</exception>
406410
</Docs>
407411
</Member>
408412
<Member MemberName="Insert">
@@ -433,11 +437,16 @@ It's safe to perform multiple concurrent read operations on a <xref:System.Text.
433437
</Parameter>
434438
</Parameters>
435439
<Docs>
436-
<param name="index">To be added.</param>
437-
<param name="propertyName">To be added.</param>
438-
<param name="value">To be added.</param>
439-
<summary>To be added.</summary>
440+
<param name="index">The zero-based index at which the property should be inserted.</param>
441+
<param name="propertyName">The property name to insert.</param>
442+
<param name="value">The JSON value to insert.</param>
443+
<summary>Inserts a property into the object at the specified index.</summary>
440444
<remarks>To be added.</remarks>
445+
<exception cref="T:System.ArgumentNullException">
446+
<paramref name="propertyName" /> is <see langword="null" />.</exception>
447+
<exception cref="T:System.ArgumentException">An element with the same key already exists in the <see cref="T:System.Text.Json.Nodes.JsonObject" />.</exception>
448+
<exception cref="T:System.ArgumentOutOfRangeException">
449+
<paramref name="index" /> is less than 0 or greater than <see cref="P:System.Text.Json.Nodes.JsonObject.Count" />.</exception>
441450
</Docs>
442451
</Member>
443452
<Member MemberName="Remove">
@@ -494,9 +503,11 @@ It's safe to perform multiple concurrent read operations on a <xref:System.Text.
494503
<Parameter Name="index" Type="System.Int32" Index="0" FrameworkAlternate="net-8.0;net-9.0;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-2.0" />
495504
</Parameters>
496505
<Docs>
497-
<param name="index">To be added.</param>
498-
<summary>To be added.</summary>
506+
<param name="index">The zero-based index of the item to remove.</param>
507+
<summary>Removes the property at the specified index.</summary>
499508
<remarks>To be added.</remarks>
509+
<exception cref="T:System.ArgumentOutOfRangeException">
510+
<paramref name="index" /> is less than 0 or greater than or equal to <see cref="P:System.Text.Json.Nodes.JsonObject.Count" />.</exception>
500511
</Docs>
501512
</Member>
502513
<Member MemberName="SetAt">
@@ -525,10 +536,14 @@ It's safe to perform multiple concurrent read operations on a <xref:System.Text.
525536
<Parameter Name="value" Type="System.Text.Json.Nodes.JsonNode" Index="1" FrameworkAlternate="net-8.0;net-9.0;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-2.0" />
526537
</Parameters>
527538
<Docs>
528-
<param name="index">To be added.</param>
529-
<param name="value">To be added.</param>
530-
<summary>To be added.</summary>
539+
<param name="index">The zero-based index of the property to set.</param>
540+
<param name="value">The JSON value to store at the specified index.</param>
541+
<summary>Sets a new property value at the specified index.</summary>
531542
<remarks>To be added.</remarks>
543+
<exception cref="T:System.ArgumentOutOfRangeException">
544+
<paramref name="index" /> is less than 0 or greater than or equal to <see cref="P:System.Text.Json.Nodes.JsonObject.Count" />.</exception>
545+
<exception cref="T:System.InvalidOperationException">
546+
<paramref name="value" /> already has a parent.</exception>
532547
</Docs>
533548
</Member>
534549
<Member MemberName="SetAt">
@@ -559,11 +574,17 @@ It's safe to perform multiple concurrent read operations on a <xref:System.Text.
559574
</Parameter>
560575
</Parameters>
561576
<Docs>
562-
<param name="index">To be added.</param>
563-
<param name="propertyName">To be added.</param>
564-
<param name="value">To be added.</param>
565-
<summary>To be added.</summary>
577+
<param name="index">The zero-based index of the property to set.</param>
578+
<param name="propertyName">The property name to store at the specified index.</param>
579+
<param name="value">The JSON value to store at the specified index.</param>
580+
<summary>Sets a new property at the specified index.</summary>
566581
<remarks>To be added.</remarks>
582+
<exception cref="T:System.ArgumentOutOfRangeException">
583+
<paramref name="index" /> is less than 0 or greater than or equal to <see cref="P:System.Text.Json.Nodes.JsonObject.Count" />.</exception>
584+
<exception cref="T:System.ArgumentException">
585+
<paramref name="propertyName" /> is already specified in a different index.</exception>
586+
<exception cref="T:System.InvalidOperationException">
587+
<paramref name="value" /> already has a parent.</exception>
567588
</Docs>
568589
</Member>
569590
<Member MemberName="System.Collections.Generic.ICollection&lt;System.Collections.Generic.KeyValuePair&lt;System.String,System.Text.Json.Nodes.JsonNode&gt;&gt;.Contains">

‎xml/System.Text.Json.Schema/JsonSchemaExporter.xml

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
</Attribute>
2525
</Attributes>
2626
<Docs>
27-
<summary>To be added.</summary>
27+
<summary>Functionality for exporting JSON schema from serialization contracts defined in <see cref="T:System.Text.Json.Serialization.Metadata.JsonTypeInfo" />.</summary>
2828
<remarks>To be added.</remarks>
2929
</Docs>
3030
<Members>
@@ -54,10 +54,10 @@
5454
</Parameter>
5555
</Parameters>
5656
<Docs>
57-
<param name="typeInfo">To be added.</param>
58-
<param name="exporterOptions">To be added.</param>
59-
<summary>To be added.</summary>
60-
<returns>To be added.</returns>
57+
<param name="typeInfo">The contract from which to resolve the JSON schema.</param>
58+
<param name="exporterOptions">The options object governing the export operation.</param>
59+
<summary>Gets the JSON schema for <paramref name="typeInfo" /> as a <see cref="T:System.Text.Json.Nodes.JsonNode" /> document.</summary>
60+
<returns>A JSON object containing the schema for <paramref name="typeInfo" />.</returns>
6161
<remarks>To be added.</remarks>
6262
</Docs>
6363
</Member>
@@ -88,11 +88,11 @@
8888
</Parameter>
8989
</Parameters>
9090
<Docs>
91-
<param name="options">To be added.</param>
92-
<param name="type">To be added.</param>
93-
<param name="exporterOptions">To be added.</param>
94-
<summary>To be added.</summary>
95-
<returns>To be added.</returns>
91+
<param name="options">The options declaring the contract for the type.</param>
92+
<param name="type">The type for which to resolve a schema.</param>
93+
<param name="exporterOptions">The options object governing the export operation.</param>
94+
<summary>Gets the JSON schema for <paramref name="type" /> as a <see cref="T:System.Text.Json.Nodes.JsonNode" /> document.</summary>
95+
<returns>A JSON object containing the schema for <paramref name="type" />.</returns>
9696
<remarks>To be added.</remarks>
9797
</Docs>
9898
</Member>

‎xml/System.Text.Json.Schema/JsonSchemaExporterContext.xml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
</Attribute>
2929
</Attributes>
3030
<Docs>
31-
<summary>To be added.</summary>
31+
<summary>Defines the context for the generated JSON schema for a particular node in a type graph.</summary>
3232
<remarks>To be added.</remarks>
3333
</Docs>
3434
<Members>
@@ -54,7 +54,7 @@
5454
<ReturnType>System.ReadOnlySpan&lt;System.String&gt;</ReturnType>
5555
</ReturnValue>
5656
<Docs>
57-
<summary>To be added.</summary>
57+
<summary>The path to the current node in the generated JSON schema.</summary>
5858
<value>To be added.</value>
5959
<remarks>To be added.</remarks>
6060
</Docs>
@@ -85,7 +85,7 @@
8585
<ReturnType>System.Text.Json.Serialization.Metadata.JsonPropertyInfo</ReturnType>
8686
</ReturnValue>
8787
<Docs>
88-
<summary>To be added.</summary>
88+
<summary>The <see cref="T:System.Text.Json.Serialization.Metadata.JsonPropertyInfo" /> if the schema is being generated for a property.</summary>
8989
<value>To be added.</value>
9090
<remarks>To be added.</remarks>
9191
</Docs>
@@ -106,7 +106,7 @@
106106
<ReturnType>System.Text.Json.Serialization.Metadata.JsonTypeInfo</ReturnType>
107107
</ReturnValue>
108108
<Docs>
109-
<summary>To be added.</summary>
109+
<summary>The <see cref="T:System.Text.Json.Serialization.Metadata.JsonTypeInfo" /> for the type being processed.</summary>
110110
<value>To be added.</value>
111111
<remarks>To be added.</remarks>
112112
</Docs>

‎xml/System.Text.Json.Schema/JsonSchemaExporterOptions.xml

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
</Attribute>
2525
</Attributes>
2626
<Docs>
27-
<summary>To be added.</summary>
27+
<summary>Configures the behavior of the <see cref="T:System.Text.Json.Schema.JsonSchemaExporter" /> APIs.</summary>
2828
<remarks>To be added.</remarks>
2929
</Docs>
3030
<Members>
@@ -61,7 +61,7 @@
6161
<ReturnType>System.Text.Json.Schema.JsonSchemaExporterOptions</ReturnType>
6262
</ReturnValue>
6363
<Docs>
64-
<summary>To be added.</summary>
64+
<summary>Gets the default configuration object used by <see cref="T:System.Text.Json.Schema.JsonSchemaExporter" />.</summary>
6565
<value>To be added.</value>
6666
<remarks>To be added.</remarks>
6767
</Docs>
@@ -88,7 +88,7 @@
8888
<ReturnType>System.Func&lt;System.Text.Json.Schema.JsonSchemaExporterContext,System.Text.Json.Nodes.JsonNode,System.Text.Json.Nodes.JsonNode&gt;</ReturnType>
8989
</ReturnValue>
9090
<Docs>
91-
<summary>To be added.</summary>
91+
<summary>Defines a callback that is invoked for every schema that is generated within the type graph.</summary>
9292
<value>To be added.</value>
9393
<remarks>To be added.</remarks>
9494
</Docs>
@@ -109,9 +109,13 @@
109109
<ReturnType>System.Boolean</ReturnType>
110110
</ReturnValue>
111111
<Docs>
112-
<summary>To be added.</summary>
112+
<summary>Determines whether non-nullable schemas should be generated for <see langword="null" /> oblivious reference types.</summary>
113113
<value>To be added.</value>
114-
<remarks>To be added.</remarks>
114+
<remarks>
115+
<para>Defaults to <see langword="false" />. Due to restrictions in the run-time representation of nullable reference types</para>
116+
<para>most occurences are <see langword="null" /> oblivious and are treated as nullable by the serializer. A notable exception to that rule</para>
117+
<para>are nullability annotations of field, property and constructor parameters which are represented in the contract metadata.</para>
118+
</remarks>
115119
</Docs>
116120
</Member>
117121
</Members>

‎xml/System.Text.Json.Serialization.Metadata/JsonObjectInfoValues`1.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@
7878
<ReturnType>System.Func&lt;System.Reflection.ICustomAttributeProvider&gt;</ReturnType>
7979
</ReturnValue>
8080
<Docs>
81-
<summary>To be added.</summary>
81+
<summary>Provides a delayed attribute provider corresponding to the deserialization constructor.</summary>
8282
<value>To be added.</value>
8383
<remarks>To be added.</remarks>
8484
</Docs>

‎xml/System.Text.Json.Serialization.Metadata/JsonParameterInfo.xml

Lines changed: 26 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
</Attribute>
2525
</Attributes>
2626
<Docs>
27-
<summary>To be added.</summary>
27+
<summary>Provides JSON serialization-related metadata about a constructor parameter.</summary>
2828
<remarks>To be added.</remarks>
2929
</Docs>
3030
<Members>
@@ -54,9 +54,12 @@
5454
<ReturnType>System.Reflection.ICustomAttributeProvider</ReturnType>
5555
</ReturnValue>
5656
<Docs>
57-
<summary>To be added.</summary>
57+
<summary>Gets a custom attribute provider for the current parameter.</summary>
5858
<value>To be added.</value>
59-
<remarks>To be added.</remarks>
59+
<remarks>
60+
<para>When resolving metadata via the built-in resolvers this will be populated with</para>
61+
<para>the underlying <see cref="T:System.Reflection.ParameterInfo" /> of the constructor metadata.</para>
62+
</remarks>
6063
</Docs>
6164
</Member>
6265
<Member MemberName="DeclaringType">
@@ -75,7 +78,7 @@
7578
<ReturnType>System.Type</ReturnType>
7679
</ReturnValue>
7780
<Docs>
78-
<summary>To be added.</summary>
81+
<summary>Gets the declaring type of the constructor.</summary>
7982
<value>To be added.</value>
8083
<remarks>To be added.</remarks>
8184
</Docs>
@@ -106,7 +109,7 @@
106109
<ReturnType>System.Object</ReturnType>
107110
</ReturnValue>
108111
<Docs>
109-
<summary>To be added.</summary>
112+
<summary>Gets a value indicating the default value if the parameter has a default value.</summary>
110113
<value>To be added.</value>
111114
<remarks>To be added.</remarks>
112115
</Docs>
@@ -127,7 +130,7 @@
127130
<ReturnType>System.Boolean</ReturnType>
128131
</ReturnValue>
129132
<Docs>
130-
<summary>To be added.</summary>
133+
<summary>Gets a value indicating whether the parameter has a default value.</summary>
131134
<value>To be added.</value>
132135
<remarks>To be added.</remarks>
133136
</Docs>
@@ -148,9 +151,12 @@
148151
<ReturnType>System.Boolean</ReturnType>
149152
</ReturnValue>
150153
<Docs>
151-
<summary>To be added.</summary>
154+
<summary>Gets a value indicating whether the parameter represents a required or init-only member initializer.</summary>
152155
<value>To be added.</value>
153-
<remarks>To be added.</remarks>
156+
<remarks>
157+
<para>Only returns <see langword="true" /> for source generated metadata which can only access</para>
158+
<para>required or init-only member initializers using object initialize expressions.</para>
159+
</remarks>
154160
</Docs>
155161
</Member>
156162
<Member MemberName="IsNullable">
@@ -169,9 +175,16 @@
169175
<ReturnType>System.Boolean</ReturnType>
170176
</ReturnValue>
171177
<Docs>
172-
<summary>To be added.</summary>
178+
<summary>Gets a value indicating whether the constructor parameter is annotated as nullable.</summary>
173179
<value>To be added.</value>
174-
<remarks>To be added.</remarks>
180+
<remarks>
181+
<para>Contracts originating from <see cref="T:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver" /> or <see cref="T:System.Text.Json.Serialization.JsonSerializerContext" />,</para>
182+
<para>derive the value of this parameter from nullable reference type annotations, including annotations</para>
183+
<para>from attributes such as <see cref="T:System.Diagnostics.CodeAnalysis.AllowNullAttribute" /> or <see cref="T:System.Diagnostics.CodeAnalysis.DisallowNullAttribute" />.</para>
184+
<para>This property has no effect on deserialization unless the <see cref="P:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations" /></para>
185+
<para>property has been enabled, in which case the serializer will reject any <see langword="null" /> deserialization results.</para>
186+
<para>This setting is in sync with the associated <see cref="P:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsSetNullable" /> property.</para>
187+
</remarks>
175188
</Docs>
176189
</Member>
177190
<Member MemberName="Name">
@@ -190,7 +203,7 @@
190203
<ReturnType>System.String</ReturnType>
191204
</ReturnValue>
192205
<Docs>
193-
<summary>To be added.</summary>
206+
<summary>Gets the name of the parameter.</summary>
194207
<value>To be added.</value>
195208
<remarks>To be added.</remarks>
196209
</Docs>
@@ -211,7 +224,7 @@
211224
<ReturnType>System.Type</ReturnType>
212225
</ReturnValue>
213226
<Docs>
214-
<summary>To be added.</summary>
227+
<summary>Gets the type of this parameter.</summary>
215228
<value>To be added.</value>
216229
<remarks>To be added.</remarks>
217230
</Docs>
@@ -232,7 +245,7 @@
232245
<ReturnType>System.Int32</ReturnType>
233246
</ReturnValue>
234247
<Docs>
235-
<summary>To be added.</summary>
248+
<summary>Gets the zero-based position of the parameter in the formal parameter list.</summary>
236249
<value>To be added.</value>
237250
<remarks>To be added.</remarks>
238251
</Docs>

‎xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -143,9 +143,9 @@ This API is for use by the output of the System.Text.Json source generator and s
143143
<ReturnType>System.Boolean</ReturnType>
144144
</ReturnValue>
145145
<Docs>
146-
<summary>To be added.</summary>
146+
<summary>Whether the parameter represents a required or init-only member initializer.</summary>
147147
<value>To be added.</value>
148-
<remarks>To be added.</remarks>
148+
<remarks>This API is for use by the output of the System.Text.Json source generator and should not be called directly.</remarks>
149149
</Docs>
150150
</Member>
151151
<Member MemberName="IsNullable">
@@ -164,9 +164,9 @@ This API is for use by the output of the System.Text.Json source generator and s
164164
<ReturnType>System.Boolean</ReturnType>
165165
</ReturnValue>
166166
<Docs>
167-
<summary>To be added.</summary>
167+
<summary>Whether the parameter allows <see langword="null" /> values.</summary>
168168
<value>To be added.</value>
169-
<remarks>To be added.</remarks>
169+
<remarks>This API is for use by the output of the System.Text.Json source generator and should not be called directly.</remarks>
170170
</Docs>
171171
</Member>
172172
<Member MemberName="Name">

0 commit comments

Comments
 (0)