Merge main into live

xml/System.Text.Json.Serialization.Metadata/JsonPropertyInfo.xml

@@ -56,11 +56,8 @@
         <summary>Gets the constructor parameter associated with the current property.</summary>
         <value>To be added.</value>
         <remarks>
-          <para>Returns the <see cref="T:System.Text.Json.Serialization.Metadata.JsonParameterInfo" /> metadata for the parameter in the</para>
-          <para>deserialization constructor that has been associated with the current property.</para>
-          <para>A constructor parameter is matched to a property or field if they are of the</para>
-          <para>same type and have the same name, up to case insensitivity. Each constructor</para>
-          <para>parameter must be matched to exactly one property of field.</para>
+          <para>Returns the <see cref="T:System.Text.Json.Serialization.Metadata.JsonParameterInfo" /> metadata for the parameter in the deserialization constructor that has been associated with the current property.</para>
+          <para>A constructor parameter is matched to a property or field if they are of the same type and have the same (case-insensitive) name. Each constructor parameter must be matched to exactly one property or field.</para>
         </remarks>
       </Docs>
     </Member>
@@ -94,11 +91,9 @@
 
 ## Remarks
 
-When resolving metadata via <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver>, this property
-             will be populated with the underlying <xref:System.Reflection.MemberInfo> of the serialized property or field.
+When resolving metadata via <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver> or <xref:System.Text.Json.Serialization.JsonSerializerContext>, this property will be populated with the underlying <xref:System.Reflection.MemberInfo> of the serialized property or field.
 
-Setting a custom attribute provider has no impact on the contract model
-             but serves as metadata for downstream contract modifiers.
+Setting a custom attribute provider has no impact on the contract model but serves as metadata for downstream contract modifiers.
 
           ]]></format>
         </remarks>
@@ -135,10 +130,9 @@ Setting a custom attribute provider has no impact on the contract model
 
 ## Remarks
 
-It is possible to use <xref:System.Text.Json.Serialization.JsonConverterFactory> instances with this property.
+It's possible to use <xref:System.Text.Json.Serialization.JsonConverterFactory> instances with this property.
 
-For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver>, the value of
-             <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.CustomConverter> will be mapped from <xref:System.Text.Json.Serialization.JsonConverterAttribute> annotations.
+For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver>, the value of <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.CustomConverter> will be mapped from <xref:System.Text.Json.Serialization.JsonConverterAttribute> annotations.
 
           ]]></format>
         </remarks>
@@ -225,10 +219,7 @@ Setting to `null` will result in the property being skipped on serialization.
         <remarks>
           <format type="text/markdown"><![CDATA[
 
-## Remarks
-
-For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver> or <xref:System.Text.Json.Serialization.JsonSerializerContext>,
-             the value of this property will be mapped from <xref:System.Text.Json.Serialization.JsonExtensionDataAttribute> annotations.
+For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver> or <xref:System.Text.Json.Serialization.JsonSerializerContext>, the value of this property will be mapped from <xref:System.Text.Json.Serialization.JsonExtensionDataAttribute> annotations.
 
           ]]></format>
         </remarks>
@@ -258,11 +249,8 @@ The current <see cref="P:System.Text.Json.Serialization.Metadata.JsonPropertyInf
         <summary>Gets or sets a value indicating whether the return type of the getter is annotated as nullable.</summary>
         <value>To be added.</value>
         <remarks>
-          <para>Contracts originating from <see cref="T:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver" /> or <see cref="T:System.Text.Json.Serialization.JsonSerializerContext" />,</para>
-          <para>derive the value of this property from nullable reference type annotations, including annotations</para>
-          <para>from attributes such as <see cref="T:System.Diagnostics.CodeAnalysis.NotNullAttribute" /> or <see cref="T:System.Diagnostics.CodeAnalysis.MaybeNullAttribute" />.</para>
-          <para>This property has no effect on serialization unless the <see cref="P:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations" /></para>
-          <para>property has been enabled, in which case the serializer will reject any <see langword="null" /> values returned by the getter.</para>
+          <para>Contracts originating from <see cref="T:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver" /> or <see cref="T:System.Text.Json.Serialization.JsonSerializerContext" />, derive the value of this property from nullable reference type annotations, including annotations from attributes such as <see cref="T:System.Diagnostics.CodeAnalysis.NotNullAttribute" /> or <see cref="T:System.Diagnostics.CodeAnalysis.MaybeNullAttribute" />.</para>
+          <para>This property has no effect on serialization unless the <see cref="P:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations" /> property has been enabled, in which case the serializer will reject any <see langword="null" /> values returned by the getter.</para>
         </remarks>
         <exception cref="T:System.InvalidOperationException">
           <para>The <see cref="T:System.Text.Json.Serialization.Metadata.JsonPropertyInfo" /> instance has been locked for further modification.</para>
@@ -326,13 +314,9 @@ The `required` keyword is currently not supported in <xref:System.Text.Json.Seri
         <summary>Gets or sets a value indicating whether the input type of the setter is annotated as nullable.</summary>
         <value>To be added.</value>
         <remarks>
-          <para>Contracts originating from <see cref="T:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver" /> or <see cref="T:System.Text.Json.Serialization.JsonSerializerContext" />,</para>
-          <para>derive the value of this property from nullable reference type annotations, including annotations</para>
-          <para>from attributes such as <see cref="T:System.Diagnostics.CodeAnalysis.AllowNullAttribute" /> or <see cref="T:System.Diagnostics.CodeAnalysis.DisallowNullAttribute" />.</para>
-          <para>This property has no effect on deserialization unless the <see cref="P:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations" /></para>
-          <para>property has been enabled, in which case the serializer will reject any <see langword="null" /> deserialization results.</para>
-          <para>If the property has been associated with a deserialization constructor parameter,</para>
-          <para>this setting reflected the nullability annotation of the parameter and not the property setter.</para>
+          <para>Contracts originating from <see cref="T:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver" /> or <see cref="T:System.Text.Json.Serialization.JsonSerializerContext" />, derive the value of this property from nullable reference type annotations, including annotations from attributes such as <see cref="T:System.Diagnostics.CodeAnalysis.AllowNullAttribute" /> or <see cref="T:System.Diagnostics.CodeAnalysis.DisallowNullAttribute" />.</para>
+          <para>This property has no effect on deserialization unless the <see cref="P:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations" /> property has been enabled, in which case the serializer will reject any <see langword="null" /> deserialization results.</para>
+          <para>If the property has been associated with a deserialization constructor parameter, this setting reflected the nullability annotation of the parameter and not the property setter.</para>
         </remarks>
         <exception cref="T:System.InvalidOperationException">
           <para>The <see cref="T:System.Text.Json.Serialization.Metadata.JsonPropertyInfo" /> instance has been locked for further modification.</para>
@@ -367,9 +351,7 @@ The `required` keyword is currently not supported in <xref:System.Text.Json.Seri
 
 The value of <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.Name> cannot conflict with that of other <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo> defined in the declaring <xref:System.Text.Json.Serialization.Metadata.JsonTypeInfo>.
 
-For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver> or <xref:System.Text.Json.Serialization.JsonSerializerContext>,
-             the value typically reflects the underlying .NET member name, the name derived from <xref:System.Text.Json.JsonSerializerOptions.PropertyNamingPolicy>,
-             or the value specified in <xref:System.Text.Json.Serialization.JsonPropertyNameAttribute>.
+For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver> or <xref:System.Text.Json.Serialization.JsonSerializerContext>, the value typically reflects the underlying .NET member name, the name derived from <xref:System.Text.Json.JsonSerializerOptions.PropertyNamingPolicy>, or the value specified in <xref:System.Text.Json.Serialization.JsonPropertyNameAttribute>.
 
           ]]></format>
         </remarks>
@@ -400,10 +382,7 @@ For contracts originating from <xref:System.Text.Json.Serialization.Metadata.Def
         <remarks>
           <format type="text/markdown"><![CDATA[
 
-## Remarks
-
-For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver> or <xref:System.Text.Json.Serialization.JsonSerializerContext>,
-            the value of this property will be mapped from <xref:System.Text.Json.Serialization.JsonNumberHandlingAttribute> annotations.
+For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver> or <xref:System.Text.Json.Serialization.JsonSerializerContext>, the value of this property will be mapped from <xref:System.Text.Json.Serialization.JsonNumberHandlingAttribute> annotations.
 
           ]]></format>
         </remarks>
@@ -480,8 +459,7 @@ For contracts originating from <xref:System.Text.Json.Serialization.Metadata.Def
 
 ## Remarks
 
-For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver> or <xref:System.Text.Json.Serialization.JsonSerializerContext>,
-            the value of this property will be mapped from <xref:System.Text.Json.Serialization.JsonPropertyOrderAttribute> annotations.
+For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver> or <xref:System.Text.Json.Serialization.JsonSerializerContext>, the value of this property will be mapped from <xref:System.Text.Json.Serialization.JsonPropertyOrderAttribute> annotations.
 
           ]]></format>
         </remarks>
@@ -581,8 +559,7 @@ The first parameter denotes the parent object, and the second parameter denotes
 
 Setting the predicate to `null` is equivalent to always serializing the property value.
 
-For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver>,
-             the value of <xref:System.Text.Json.Serialization.JsonIgnoreAttribute.Condition> will map to this predicate.
+For contracts originating from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver>, the value of <xref:System.Text.Json.Serialization.JsonIgnoreAttribute.Condition> will map to this predicate.
 
           ]]></format>
         </remarks>

xml/System.Text.Json.Serialization/JsonSourceGenerationMode.xml

@@ -44,7 +44,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>When specified on <see cref="P:System.Text.Json.Serialization.JsonSourceGenerationOptionsAttribute.GenerationMode" />, indicates that both type-metadata initialization logic and optimized serialization logic should be generated for all types. When specified on <see cref="P:System.Text.Json.Serialization.JsonSerializableAttribute.GenerationMode" />, indicates that the setting on <see cref="P:System.Text.Json.Serialization.JsonSourceGenerationOptionsAttribute.GenerationMode" /> should be used.</summary>
+        <summary>When specified on <see cref="P:System.Text.Json.Serialization.JsonSourceGenerationOptionsAttribute.GenerationMode">JsonSourceGenerationOptionsAttribute.GenerationMode</see>, indicates that both type-metadata initialization logic and optimized serialization logic should be generated for all types. When specified on <see cref="P:System.Text.Json.Serialization.JsonSerializableAttribute.GenerationMode">JsonSerializableAttribute.GenerationMode</see>, indicates that the setting on <see cref="P:System.Text.Json.Serialization.JsonSourceGenerationOptionsAttribute.GenerationMode">JsonSourceGenerationOptionsAttribute.GenerationMode</see> should be used.</summary>
       </Docs>
     </Member>
     <Member MemberName="Metadata">

xml/System.Text.Json.Serialization/ReferenceHandler.xml

@@ -135,11 +135,11 @@
 
 * For the metadata properties within the JSON to be considered well-formed, they must follow these rules:
 
-  * The `$id` metadata property must be the first property in the JSON object.
+  * Unless <xref:System.Text.Json.JsonSerializerOptions.AllowOutOfOrderMetadataProperties> is set to `true`, the `$id` metadata property must be the first property in the JSON object.
   * A JSON object that contains a `$ref` metadata property must not contain any other properties.
   * The value of the `$ref` metadata property must refer to an `$id` that has appeared earlier in the JSON.
   * The value of the `$id` and `$ref` metadata properties must be a JSON string.
-  * For enumerable types, such as <xref:System.Collections.Generic.List%601>, the JSON array must be nested within a JSON object containing an `$id` and `$values` metadata property, in that order.
+  * For enumerable types, such as <xref:System.Collections.Generic.List%601>, the JSON array must be nested within a JSON object containing an `$id` and `$values` metadata property, in that order. (However, the order is not important if <xref:System.Text.Json.JsonSerializerOptions.AllowOutOfOrderMetadataProperties> is set to `true`.)
   * For enumerable types, the `$values` metadata property must be a JSON array.
   * The `$values` metadata property is only valid when referring to enumerable types.