From 711bb3d59481e924c2b3bee51033cd8741cd8881 Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Fri, 23 Sep 2022 12:29:17 -0700
Subject: [PATCH 1/5] fix up stj comments

---
 .../JsonCollectionInfoValues`1.xml            |  2 +-
 .../JsonObjectInfoValues`1.xml                | 10 +------
 .../JsonParameterInfoValues.xml               |  9 +------
 .../JsonPropertyInfo.xml                      | 27 ++++++++++---------
 .../JsonTypeInfo.xml                          | 10 +------
 5 files changed, 19 insertions(+), 39 deletions(-)

diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonCollectionInfoValues`1.xml b/xml/System.Text.Json.Serialization.Metadata/JsonCollectionInfoValues`1.xml
index 6ca89475c16..5d37257d828 100644
--- a/xml/System.Text.Json.Serialization.Metadata/JsonCollectionInfoValues`1.xml
+++ b/xml/System.Text.Json.Serialization.Metadata/JsonCollectionInfoValues`1.xml
@@ -26,7 +26,7 @@
   <Docs>
     <typeparam name="TCollection">The collection type.</typeparam>
     <summary>Provides serialization metadata about a collection type.</summary>
-    <remarks>This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.</remarks>
+    <remarks>To be added.</remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonObjectInfoValues`1.xml b/xml/System.Text.Json.Serialization.Metadata/JsonObjectInfoValues`1.xml
index 8cf3aa27e2c..b9d6cc673e6 100644
--- a/xml/System.Text.Json.Serialization.Metadata/JsonObjectInfoValues`1.xml
+++ b/xml/System.Text.Json.Serialization.Metadata/JsonObjectInfoValues`1.xml
@@ -26,15 +26,7 @@
   <Docs>
     <typeparam name="T">The object type to serialize or deserialize.</typeparam>
     <summary>Provides serialization metadata about an object type with constructors, properties, and fields.</summary>
-    <remarks>
-      <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.
-
-      ]]></format>
-    </remarks>
+    <remarks>To be added.</remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml b/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
index eca6e84267d..29163a6fdde 100644
--- a/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
+++ b/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
@@ -22,14 +22,7 @@
   </Attributes>
   <Docs>
     <summary>Provides information about a constructor parameter required for JSON deserialization.</summary>
-    <remarks>
-      <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.
-
-      ]]></format>
+    <remarks>To be added.</format>
     </remarks>
   </Docs>
   <Members>
diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonPropertyInfo.xml b/xml/System.Text.Json.Serialization.Metadata/JsonPropertyInfo.xml
index 8397803ebe7..4358603a9a2 100644
--- a/xml/System.Text.Json.Serialization.Metadata/JsonPropertyInfo.xml
+++ b/xml/System.Text.Json.Serialization.Metadata/JsonPropertyInfo.xml
@@ -16,15 +16,7 @@
   <Interfaces />
   <Docs>
     <summary>Provides JSON serialization-related metadata about a property or field.</summary>
-    <remarks>
-      <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.
-
-      ]]></format>
-    </remarks>
+    <remarks>To be added.</remarks>
   </Docs>
   <Members>
     <Member MemberName="AttributeProvider">
@@ -177,10 +169,21 @@ The current <see cref="P:System.Text.Json.Serialization.Metadata.JsonPropertyInf
       <Docs>
         <summary>Gets or sets a value that indicates whether the current property is required for deserialization to be successful.</summary>
         <value>To be added.</value>
-        <remarks>For contracts originating from <see cref="T:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver" /> or <see cref="T:System.Text.Json.Serialization.JsonSerializerContext" />, the value of this property will be mapped from <see cref="T:System.Text.Json.Serialization.JsonRequiredAttribute" /> annotations.
-             For contracts using <see cref="T:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver" />, the value of this property will also map from properties that have the <see langword="required" /> modifier, unless deserialization uses a constructor that populates all required properties and that has <see cref="T:System.Diagnostics.CodeAnalysis.SetsRequiredMembersAttribute" />.
-             <see langword="required" /> keyword is currently not supported in <see cref="T:System.Text.Json.Serialization.JsonSerializerContext" /> contracts.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For contracts that originate from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver> or <xref:System.Text.Json.Serialization.JsonSerializerContext>, the value of this property is mapped from <xref:System.Text.Json.Serialization.JsonRequiredAttribute> annotations.
+
+For contracts that use <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver>, the value of this property is also mapped from properties that have the <see langword="required" /> modifier, unless deserialization uses a constructor that populates all required properties and has <xref:System.Diagnostics.CodeAnalysis.SetsRequiredMembersAttribute>.
+
+The <see langword="required" /> keyword is currently not supported in <xref:System.Text.Json.Serialization.JsonSerializerContext> contracts.
+
+]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">The <see cref="T:System.Text.Json.Serialization.Metadata.JsonPropertyInfo" /> instance has been locked for further modification.</exception>
+        <related type="Article" href="/dotnet/standard/serialization/system-text-json/required-properties">Required properties</related>
       </Docs>
     </Member>
     <Member MemberName="Name">
diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonTypeInfo.xml b/xml/System.Text.Json.Serialization.Metadata/JsonTypeInfo.xml
index 6ebcd74529f..a2dbe157d2c 100644
--- a/xml/System.Text.Json.Serialization.Metadata/JsonTypeInfo.xml
+++ b/xml/System.Text.Json.Serialization.Metadata/JsonTypeInfo.xml
@@ -20,15 +20,7 @@
   <Interfaces />
   <Docs>
     <summary>Provides JSON serialization-related metadata about a type.</summary>
-    <remarks>
-      <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.
-
-      ]]></format>
-    </remarks>
+    <remarks>To be added.</remarks>
   </Docs>
   <Members>
     <Member MemberName="Converter">

From 6fe5e271dc51084cd4f006aef3a7c224ed92b490 Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Fri, 23 Sep 2022 14:06:55 -0700
Subject: [PATCH 2/5] Fix closing tag

---
 .../JsonParameterInfoValues.xml                                | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml b/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
index 29163a6fdde..04cbefa3b15 100644
--- a/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
+++ b/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
@@ -22,8 +22,7 @@
   </Attributes>
   <Docs>
     <summary>Provides information about a constructor parameter required for JSON deserialization.</summary>
-    <remarks>To be added.</format>
-    </remarks>
+    <remarks>To be added.</remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">

From 3aca7607ef107fbc3f5e421f439c41b12e3e7e73 Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Fri, 23 Sep 2022 14:42:36 -0700
Subject: [PATCH 3/5] Fix invalid HTML

---
 .../JsonPropertyInfo.xml                                      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonPropertyInfo.xml b/xml/System.Text.Json.Serialization.Metadata/JsonPropertyInfo.xml
index 4358603a9a2..1b93bade3a8 100644
--- a/xml/System.Text.Json.Serialization.Metadata/JsonPropertyInfo.xml
+++ b/xml/System.Text.Json.Serialization.Metadata/JsonPropertyInfo.xml
@@ -176,9 +176,9 @@ The current <see cref="P:System.Text.Json.Serialization.Metadata.JsonPropertyInf
 
 For contracts that originate from <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver> or <xref:System.Text.Json.Serialization.JsonSerializerContext>, the value of this property is mapped from <xref:System.Text.Json.Serialization.JsonRequiredAttribute> annotations.
 
-For contracts that use <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver>, the value of this property is also mapped from properties that have the <see langword="required" /> modifier, unless deserialization uses a constructor that populates all required properties and has <xref:System.Diagnostics.CodeAnalysis.SetsRequiredMembersAttribute>.
+For contracts that use <xref:System.Text.Json.Serialization.Metadata.DefaultJsonTypeInfoResolver>, the value of this property is also mapped from properties that have the `required` modifier, unless deserialization uses a constructor that populates all required properties and has <xref:System.Diagnostics.CodeAnalysis.SetsRequiredMembersAttribute>.
 
-The <see langword="required" /> keyword is currently not supported in <xref:System.Text.Json.Serialization.JsonSerializerContext> contracts.
+The `required` keyword is currently not supported in <xref:System.Text.Json.Serialization.JsonSerializerContext> contracts.
 
 ]]></format>
         </remarks>

From 2fe9e1a4250cdee835b1d98d425aec21b1c3cc4f Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Mon, 26 Sep 2022 09:57:25 -0700
Subject: [PATCH 4/5] respond to feedback

---
 .../JsonCollectionInfoValues`1.xml                              | 2 +-
 .../JsonObjectInfoValues`1.xml                                  | 2 +-
 .../JsonParameterInfoValues.xml                                 | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonCollectionInfoValues`1.xml b/xml/System.Text.Json.Serialization.Metadata/JsonCollectionInfoValues`1.xml
index 5d37257d828..6ca89475c16 100644
--- a/xml/System.Text.Json.Serialization.Metadata/JsonCollectionInfoValues`1.xml
+++ b/xml/System.Text.Json.Serialization.Metadata/JsonCollectionInfoValues`1.xml
@@ -26,7 +26,7 @@
   <Docs>
     <typeparam name="TCollection">The collection type.</typeparam>
     <summary>Provides serialization metadata about a collection type.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.</remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonObjectInfoValues`1.xml b/xml/System.Text.Json.Serialization.Metadata/JsonObjectInfoValues`1.xml
index b9d6cc673e6..f5f44a4d845 100644
--- a/xml/System.Text.Json.Serialization.Metadata/JsonObjectInfoValues`1.xml
+++ b/xml/System.Text.Json.Serialization.Metadata/JsonObjectInfoValues`1.xml
@@ -26,7 +26,7 @@
   <Docs>
     <typeparam name="T">The object type to serialize or deserialize.</typeparam>
     <summary>Provides serialization metadata about an object type with constructors, properties, and fields.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.</remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml b/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
index 29163a6fdde..dac92b75990 100644
--- a/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
+++ b/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
@@ -22,7 +22,7 @@
   </Attributes>
   <Docs>
     <summary>Provides information about a constructor parameter required for JSON deserialization.</summary>
-    <remarks>To be added.</format>
+    <remarks>This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.</format>
     </remarks>
   </Docs>
   <Members>

From 5bfff1217aab859d950811d291c17867096be03e Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Mon, 26 Sep 2022 10:06:49 -0700
Subject: [PATCH 5/5] fix tags

---
 .../JsonParameterInfoValues.xml                                | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml b/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
index dac92b75990..338496cab0c 100644
--- a/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
+++ b/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfoValues.xml
@@ -22,8 +22,7 @@
   </Attributes>
   <Docs>
     <summary>Provides information about a constructor parameter required for JSON deserialization.</summary>
-    <remarks>This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.</format>
-    </remarks>
+    <remarks>This API is intended for use by the output of the System.Text.Json source generator and should not be called directly.</remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">