Augment AllowOutOfOrderMetadataProperties remarks with buffering/backtracking detail (#12402)

Author: eiriktsarpalis

xml/System.Text.Json.Serialization/JsonSourceGenerationOptionsAttribute.xml

@@ -125,7 +125,19 @@
       <Docs>
         <summary>Specifies the default value of <see cref="P:System.Text.Json.JsonSerializerOptions.AllowOutOfOrderMetadataProperties" /> when set.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This property sets the default value for <xref:System.Text.Json.JsonSerializerOptions.AllowOutOfOrderMetadataProperties> on the generated serializer options.
+
+When this property is enabled, JSON metadata properties such as `$id`, `$type`, and `$ref` are allowed to appear after regular properties during deserialization. However, this has performance implications. The deserializer must buffer entire JSON objects in memory, and with nested objects, it might need to backtrack once per nesting level, resulting in worst-case **O(n × d)** deserialization time (where *n* is the payload length and *d* is the object graph depth).
+
+For more details on the performance tradeoffs, see <xref:System.Text.Json.JsonSerializerOptions.AllowOutOfOrderMetadataProperties>.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="AllowTrailingCommas">

xml/System.Text.Json/JsonSerializerOptions.xml

@@ -231,7 +231,19 @@ similar to how <xref:System.Text.Json.Serialization.Metadata.JsonTypeInfoResolve
         <summary>Gets or sets a value that indicates whether JSON metadata properties can be specified after regular properties in a deserialized JSON object.</summary>
         <value>
           <see langword="true" /> if JSON metadata properties, such as \\$id and \\$type, aren't required to be specified at the very start of the deserialized JSON object; <see langword="false" /> if JSON metadata properties must be specified before regular properties.</value>
-        <remarks>If you enable this setting, it can result in over-buffering when deserializing large JSON payloads in the context of streaming deserialization.
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+By default, `System.Text.Json` requires that JSON metadata properties such as `$id`, `$type`, and `$ref` appear at the very start of a JSON object. Setting this property to `true` relaxes that requirement, allowing metadata to appear after regular properties. This is useful when consuming JSON from producers that don't guarantee metadata ordering.
+
+However, there are performance implications when this property is enabled:
+
+- **Buffering**: When this property is enabled, the deserializer can no longer process object properties in a single forward pass. Because metadata properties appearing later in the object (for example, a `$type` discriminator) can change how all earlier properties should be interpreted, the deserializer must buffer the entire JSON object in memory before it can commit to a deserialization strategy. In streaming deserialization scenarios, this can significantly increase memory consumption, especially for large JSON payloads.
+- **Backtracking**: With nested objects, the cost of out-of-order metadata is multiplicative. The deserializer might need to backtrack (that is, reread and reprocess previously buffered data) once for each level of nesting depth in the incoming object graph. This means the worst-case deserialization time is **O(n × d)**, where *n* is the length of the JSON input and *d* is the depth of the object graph.
+
+          ]]></format>
         </remarks>
         <exception cref="T:System.InvalidOperationException">This property is set after serialization or deserialization has occurred.</exception>
       </Docs>