Merge pull request #9395 from dotnet/main

includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md

@@ -7,7 +7,7 @@ The methods for manipulating zip archives and their file entries are spread acro
 |Create a zip archive from a directory|<xref:System.IO.Compression.ZipFile.CreateFromDirectory%2A?displayProperty=nameWithType>|
 |Extract the contents of a zip archive to a directory|<xref:System.IO.Compression.ZipFile.ExtractToDirectory%2A?displayProperty=nameWithType>|
 |Add new files to an existing zip archive|<xref:System.IO.Compression.ZipArchive.CreateEntry%2A?displayProperty=nameWithType>|
-|Retrieve an file in a zip archive|<xref:System.IO.Compression.ZipArchive.GetEntry%2A?displayProperty=nameWithType>|
+|Retrieve a file in a zip archive|<xref:System.IO.Compression.ZipArchive.GetEntry%2A?displayProperty=nameWithType>|
 |Retrieve all of the files in a zip archive|<xref:System.IO.Compression.ZipArchive.Entries%2A?displayProperty=nameWithType>|
 |To open a stream to an individual file contained in a zip archive|<xref:System.IO.Compression.ZipArchiveEntry.Open%2A?displayProperty=nameWithType>|
 |Delete a file from a zip archive|<xref:System.IO.Compression.ZipArchiveEntry.Delete%2A?displayProperty=nameWithType>|

xml/System.Runtime.Serialization.Json/DataContractJsonSerializer.xml

@@ -67,15 +67,15 @@
   <Docs>
     <summary>Serializes objects to the JavaScript Object Notation (JSON) and deserializes JSON data to objects. This class cannot be inherited.</summary>
     <remarks>
-      <format type="text/markdown"><![CDATA[  
-  
-## Remarks 
- For most scenarios that involve serializing to JSON and deserializing from JSON, we recommend the [APIs in the System.Text.Json namespace](/dotnet/standard/serialization/system-text-json-overview). 
- 
- If your scenario requires the <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer> class, you can use it to serialize instances of a type into a JSON document and to deserialize a JSON document into an instance of a type. For example, you can create a type named `Person` with properties that contain essential data, such as a name and address. You can then create and manipulate an instance of the `Person` class and write all of its property values in a JSON document for later retrieval. This JSON document can later be deserialized into the `Person` class or another class with an equivalent data contract.  
-  
- If an error occurs during the serialization of an outgoing reply on the server or the reply operation throws an exception for some other reason, it may not get returned to the client as a fault.  
-  
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+ For most scenarios that involve serializing to JSON and deserializing from JSON, we recommend the [APIs in the System.Text.Json namespace](/dotnet/standard/serialization/system-text-json/overview).
+
+ If your scenario requires the <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer> class, you can use it to serialize instances of a type into a JSON document and to deserialize a JSON document into an instance of a type. For example, you can create a type named `Person` with properties that contain essential data, such as a name and address. You can then create and manipulate an instance of the `Person` class and write all of its property values in a JSON document for later retrieval. This JSON document can later be deserialized into the `Person` class or another class with an equivalent data contract.
+
+ If an error occurs during the serialization of an outgoing reply on the server or the reply operation throws an exception for some other reason, it may not get returned to the client as a fault.
+
  ]]></format>
     </remarks>
   </Docs>
@@ -690,11 +690,11 @@
         <summary>Gets a surrogate type that is currently active for a given <see cref="T:System.Runtime.Serialization.IDataContractSurrogate" /> instance. Surrogates can extend the serialization or deserialization process.</summary>
         <value>An implementation of the <see cref="T:System.Runtime.Serialization.IDataContractSurrogate" /> class.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The <xref:System.Runtime.Serialization.IDataContractSurrogate> can be used to customize how instances of a type are serialized and deserialized. For example, it can be used to enable serialization of legacy types that are not serializable, that is, types to which the <xref:System.Runtime.Serialization.DataContractAttribute> attribute has not been applied.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ The <xref:System.Runtime.Serialization.IDataContractSurrogate> can be used to customize how instances of a type are serialized and deserialized. For example, it can be used to enable serialization of legacy types that are not serializable, that is, types to which the <xref:System.Runtime.Serialization.DataContractAttribute> attribute has not been applied.
+
  ]]></format>
         </remarks>
       </Docs>
@@ -869,11 +869,11 @@
         <value>
           <see langword="true" /> to ignore unknown data and <see cref="T:System.Runtime.Serialization.IExtensibleDataObject" />; otherwise, <see langword="false" />.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.IgnoreExtensionDataObject%2A> property affects types to which a <xref:System.Runtime.Serialization.DataContractAttribute> attribute has been applied and that also implement the <xref:System.Runtime.Serialization.IExtensibleDataObject> interface. In this case when <xref:System.Runtime.Serialization.IExtensibleDataObject> is `true`, data added in future versions of the contract is ignored on read and write. For more information, see [Forward-Compatible Data Contracts](/dotnet/framework/wcf/feature-details/forward-compatible-data-contracts).  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ The <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.IgnoreExtensionDataObject%2A> property affects types to which a <xref:System.Runtime.Serialization.DataContractAttribute> attribute has been applied and that also implement the <xref:System.Runtime.Serialization.IExtensibleDataObject> interface. In this case when <xref:System.Runtime.Serialization.IExtensibleDataObject> is `true`, data added in future versions of the contract is ignored on read and write. For more information, see [Forward-Compatible Data Contracts](/dotnet/framework/wcf/feature-details/forward-compatible-data-contracts).
+
  ]]></format>
         </remarks>
       </Docs>
@@ -942,13 +942,13 @@
         <returns>
           <see langword="true" /> if the reader is positioned correctly; otherwise, <see langword="false" />.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- The <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.IsStartObject%2A> determines whether it can read a object by checking that it is positioned on an XML element. It also examines the name and namespace of the XML element that the reader is positioned at and compares the values to the expected name and namespace. The expected name can be set with the `rootName` value passed into the constructor (if present), or is "root" if absent. The expected namespace is the empty string.  
-  
- Note that this method is intended for advanced scenarios when working with XML mapped from JSON.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ The <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.IsStartObject%2A> determines whether it can read a object by checking that it is positioned on an XML element. It also examines the name and namespace of the XML element that the reader is positioned at and compares the values to the expected name and namespace. The expected name can be set with the `rootName` value passed into the constructor (if present), or is "root" if absent. The expected namespace is the empty string.
+
+ Note that this method is intended for advanced scenarios when working with XML mapped from JSON.
+
  ]]></format>
         </remarks>
       </Docs>
@@ -1006,11 +1006,11 @@
         <returns>
           <see langword="true" /> if the reader is positioned correctly; otherwise, <see langword="false" />.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- This method checks whether the reader is positioned on an element that can be deserialized, and returns `true` if it is. To return `true`, the found element must have the expected name.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ This method checks whether the reader is positioned on an element that can be deserialized, and returns `true` if it is. To return `true`, the found element must have the expected name.
+
  ]]></format>
         </remarks>
       </Docs>
@@ -1095,13 +1095,13 @@
         <summary>Gets the maximum number of items in an object graph that the serializer serializes or deserializes in one read or write call.</summary>
         <value>The maximum number of items to serialize or deserialize.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- This property can be set using a constructor. For a list, see <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.%23ctor%2A>.  
-  
- The <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.MaxItemsInObjectGraph%2A> property specifies the maximum number of objects that the serializer serializes or deserializes in a single <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.ReadObject%2A> or <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.WriteObject%2A> method call. The method always reads one root object, but this object may have other objects in its data members. Those objects may have other objects. The default is <xref:System.Int32.MaxValue>. Note that when serializing or deserializing arrays, every array entry counts as a separate object. Also, note that some objects may have a large memory representation, so this quota alone may not be sufficient to prevent Denial of Service attacks. For more information, see [Security Considerations for Data](/dotnet/framework/wcf/feature-details/security-considerations-for-data). If you need to increase this quota beyond its default value, it is important to do so both on the sending (serializing) and receiving (deserializing) sides. It applies both when reading and writing data.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ This property can be set using a constructor. For a list, see <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.%23ctor%2A>.
+
+ The <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.MaxItemsInObjectGraph%2A> property specifies the maximum number of objects that the serializer serializes or deserializes in a single <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.ReadObject%2A> or <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer.WriteObject%2A> method call. The method always reads one root object, but this object may have other objects in its data members. Those objects may have other objects. The default is <xref:System.Int32.MaxValue>. Note that when serializing or deserializing arrays, every array entry counts as a separate object. Also, note that some objects may have a large memory representation, so this quota alone may not be sufficient to prevent Denial of Service attacks. For more information, see [Security Considerations for Data](/dotnet/framework/wcf/feature-details/security-considerations-for-data). If you need to increase this quota beyond its default value, it is important to do so both on the sending (serializing) and receiving (deserializing) sides. It applies both when reading and writing data.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">The number of items exceeds the maximum value.</exception>
@@ -1591,11 +1591,11 @@
         <param name="writer">An <see cref="T:System.Xml.XmlDictionaryWriter" /> used to write the XML document to map to JSON.</param>
         <summary>Writes the closing XML element to an XML document, using an <see cref="T:System.Xml.XmlDictionaryWriter" />, which can be mapped to JavaScript Object Notation (JSON).</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- Note that this method is intended for advanced scenarios when working with XML mapped from JSON.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ Note that this method is intended for advanced scenarios when working with XML mapped from JSON.
+
  ]]></format>
         </remarks>
       </Docs>

xml/System.Text.Encodings.Web/JavaScriptEncoder.xml

@@ -34,10 +34,10 @@
   <Docs>
     <summary>Represents a JavaScript character encoding.</summary>
     <remarks>
-      <format type="text/markdown"><![CDATA[ 
+      <format type="text/markdown"><![CDATA[
 
-## Remarks  
- The source code for this type is available in the [System.Text.Encodings.Web project](https://github.com/dotnet/runtime/tree/main/src/libraries/System.Text.Encodings.Web) on GitHub. Unit tests that can also serve as code examples are found in the [System.Text.Encodings.Web/tests](https://github.com/dotnet/runtime/tree/main/src/libraries/System.Text.Encodings.Web/tests) folder on GitHub.  
+## Remarks
+ The source code for this type is available in the [System.Text.Encodings.Web project](https://github.com/dotnet/runtime/tree/main/src/libraries/System.Text.Encodings.Web) on GitHub. Unit tests that can also serve as code examples are found in the [System.Text.Encodings.Web/tests](https://github.com/dotnet/runtime/tree/main/src/libraries/System.Text.Encodings.Web/tests) folder on GitHub.
  ]]></format>
     </remarks>
   </Docs>
@@ -140,10 +140,10 @@
         <summary>Creates a new instance of the JavaScriptEncoder class that specifies characters the encoder is allowed to not encode.</summary>
         <returns>A new instance of the <see cref="T:System.Text.Encodings.Web.JavaScriptEncoder" /> class.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[ 
+          <format type="text/markdown"><![CDATA[
 
-## Remarks  
- Some characters in `allowedRanges` might still be encoded; that is, this parameter indicates what ranges the encoder is allowed to not encode, not what characters it must not encode.  
+## Remarks
+ Some characters in `allowedRanges` might still be encoded; that is, this parameter indicates what ranges the encoder is allowed to not encode, not what characters it must not encode.
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
@@ -215,7 +215,7 @@ Unlike the <xref:System.Text.Encodings.Web.JavaScriptEncoder.Default> encoding (
 
 Unlike the <xref:System.Text.Encodings.Web.JavaScriptEncoder.Default> encoder, this encoder instance allows some other characters (such as '+') to go through unescaped and therefore must be used cautiously.
 
-For more information about why this could be **unsafe**, see [Serialize all characters](/dotnet/standard/serialization/system-text-json-character-encoding#serialize-all-characters).
+For more information about why this could be **unsafe**, see [Serialize all characters](/dotnet/standard/serialization/system-text-json/character-encoding#serialize-all-characters).
 
           ]]></format>
         </remarks>

xml/System.Text.Json.Serialization/JsonConverter.xml

@@ -35,7 +35,7 @@
 
 ## Remarks
 
-For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json-converters-how-to).
+For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json/converters-how-to).
 
  ]]></format>
     </remarks>

xml/System.Text.Json.Serialization/JsonConverterAttribute.xml

@@ -53,8 +53,8 @@ When placed on a property, the specified converter will always be used.
 
 When placed on a type, the specified converter will be used unless a compatible converter is added to the <xref:System.Text.Json.JsonSerializerOptions.Converters?displayProperty=nameWithType> collection or there is another <xref:System.Text.Json.Serialization.JsonConverterAttribute> on a property of the same type.
 
-For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json-converters-how-to#register-a-custom-converter). 
-        
+For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json/converters-how-to#register-a-custom-converter).
+
           ]]></format>
     </remarks>
   </Docs>

xml/System.Text.Json.Serialization/JsonConverterFactory.xml

@@ -37,7 +37,7 @@
 
 This is useful for converters supporting generics, such as a converter for <xref:System.Collections.Generic.List`1>.
 
-For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json-converters-how-to#register-a-custom-converter).
+For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json/converters-how-to#register-a-custom-converter).
 
           ]]></format>
     </remarks>
@@ -106,7 +106,7 @@ For more information, see [How to write custom converters for JSON serialization
 
 ## Remarks
 
-For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json-converters-how-to#sample-factory-pattern-converter).
+For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json/converters-how-to#sample-factory-pattern-converter).
 
  ]]></format>
         </remarks>

xml/System.Text.Json.Serialization/JsonConverter`1.xml

@@ -46,7 +46,7 @@
 
 ## Remarks
 
-For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json-converters-how-to).
+For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json/converters-how-to).
 
  ]]></format>
     </remarks>
@@ -109,7 +109,7 @@ For more information, see [How to write custom converters for JSON serialization
 
 The default implementation is to return `true` when `typeToConvert` equals `typeof(T)`.
 
-For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json-converters-how-to#steps-to-follow-the-basic-pattern).
+For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json/converters-how-to#steps-to-follow-the-basic-pattern).
 
           ]]></format>
         </remarks>
@@ -184,7 +184,7 @@ The default value is `true` for converters for value types, and `false` for conv
 
 ## Remarks
 
-For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json-converters-how-to#steps-to-follow-the-basic-pattern).
+For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json/converters-how-to#steps-to-follow-the-basic-pattern).
 
  ]]></format>
         </remarks>
@@ -295,7 +295,7 @@ This method should be overridden in custom converters of types used in deseriali
 
 A converter may throw any exception, but it should throw <xref:System.Text.Json.JsonException> when the JSON cannot be created.
 
-For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json-converters-how-to#steps-to-follow-the-basic-pattern).
+For more information, see [How to write custom converters for JSON serialization](/dotnet/standard/serialization/system-text-json/converters-how-to#steps-to-follow-the-basic-pattern).
 
           ]]></format>
         </remarks>