dotnet · rpetrusha · Jun 26, 2019 · Jun 13, 2019 · Jun 13, 2019 · Jun 13, 2019
diff --git a/xml/System.Runtime.ConstrainedExecution/Consistency.xml b/xml/System.Runtime.ConstrainedExecution/Consistency.xml
@@ -177,17 +177,7 @@
       </ReturnValue>
       <MemberValue>3</MemberValue>
       <Docs>
-        <summary>In the face of exceptional conditions, the method is guaranteed not to corrupt state.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-
-## Remarks  
-
-> [!NOTE]
->  This does not guarantee that the method will never fail; however, it does guarantee that such a failure will never corrupt state.  
-
- ]]></format>
-        </remarks>
+        <summary>In the face of exceptional conditions, the method is guaranteed not to corrupt state. (This does not guarantee that the method will never fail; however, it does guarantee that such a failure will never corrupt state.)</summary>
       </Docs>
     </Member>
   </Members>

diff --git a/xml/System.Runtime.InteropServices/ClassInterfaceType.xml b/xml/System.Runtime.InteropServices/ClassInterfaceType.xml
@@ -106,15 +106,8 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>Indicates that the class only supports late binding for COM clients. A <see langword="dispinterface" /> for the class is automatically exposed to COM clients on request. The type library produced by [Tlbexp.exe (Type Library Exporter)](~/docs/framework/tools/tlbexp-exe-type-library-exporter.md) does not contain type information for the <see langword="dispinterface" /> in order to prevent clients from caching the DISPIDs of the interface. The <see langword="dispinterface" /> does not exhibit the versioning problems described in <see cref="T:System.Runtime.InteropServices.ClassInterfaceAttribute" /> because clients can only late-bind to the interface.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-
-## Remarks  
- This is the default setting for <xref:System.Runtime.InteropServices.ClassInterfaceAttribute>.  
-
- ]]></format>
-        </remarks>
+        <summary><para>Indicates that the class only supports late binding for COM clients. A <see langword="dispinterface" /> for the class is automatically exposed to COM clients on request. The type library produced by <see href="~/docs/framework/tools/tlbexp-exe-type-library-exporter.md">Tlbexp.exe (Type Library Exporter)</see> does not contain type information for the <see langword="dispinterface" /> in order to prevent clients from caching the DISPIDs of the interface. The <see langword="dispinterface" /> does not exhibit the versioning problems described in <see cref="T:System.Runtime.InteropServices.ClassInterfaceAttribute" /> because clients can only late-bind to the interface.</para>
+        <para>This is the default setting for <see cref="T:System.Runtime.InteropServices.ClassInterfaceAttribute" />. </para></summary>
       </Docs>
     </Member>
     <Member MemberName="AutoDual">
@@ -213,4 +206,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>
diff --git a/xml/System.Runtime.Remoting.Metadata/SoapOption.xml b/xml/System.Runtime.Remoting.Metadata/SoapOption.xml
@@ -31,9 +31,44 @@
     <remarks>
       <format type="text/markdown"><![CDATA[  
 
-## Remarks  
- The <xref:System.Runtime.Remoting.Metadata.SoapOption> enumeration is used to specify instructions to the .NET Framework on how it will generate the SOAP.  
+## Remarks
+
+The `SoapOption` enumeration is used to specify instructions to the .NET Framework on how it will generate the SOAP.  
+
+For example, while a class by default (with the `SoapOptions.None` enumeration value) might be remoted in the SOAP format as:  
 
+```xml
+<member1>10</member1>  
+<member2 id="ref-3">hello</member2>  
+<member3 href="#ref-3"/>  
+<member4 href="#ref-4"/>  
+<member4shared href="#ref-4"/>  
+<member5 href="#ref-5"/>  
+<member6 id="ref-6" xsi:type="SOAP-ENC:string">Hello World</member6>  
+<str1 id="ref-7">hello &#60; world</str1>  
+<str2 id="ref-8">&#60;</str2>  
+<str3 id="ref-9">&#60; world</str3>  
+<str4 href="#ref-7"/>  
+```
+
+Remoting serialization with the `SoapOptions.XsdString` option produces the following XML:
+
+```xml
+<member1 xsi:type="xsd:int">10</member1>  
+<member2 xsi:type="xsd:string">hello</member2>  
+<member3 xsi:type="xsd:string">hello</member3>  
+<member4 href="#ref-3"/>  
+<member4shared href="#ref-3"/>  
+<member5 href="#ref-4"/>  
+<member6 xsi:type="xsd:string">Hello World</member6>  
+<str1 xsi:type="xsd:string">hello &#60; world</str1>  
+<str2 xsi:type="xsd:string">&#60;</str2>  
+<str3 xsi:type="xsd:string">&#60; world</str3>  
+<str4 xsi:type="xsd:string">hello &#60; world</str4>  
+```  
+
+For more information about SOAP envelopes, see [www.w3.org/tr/soap/#_Toc478383494](https://www.w3.org/TR/soap/#_Toc478383494).
+
  ]]></format>
     </remarks>
     <forInternalUseOnly />
@@ -179,49 +214,9 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>Indicates that the output SOAP string type in a SOAP Envelope is using the <see langword="XSD" /> prefix, and that the resulting XML does not have an ID attribute for the string.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-
-## Remarks  
- For example, while a class by default might be remoted in the SOAP format as  
-
-```  
-<member1>10</member1>  
-<member2 id="ref-3">hello</member2>  
-<member3 href="#ref-3"/>  
-<member4 href="#ref-4"/>  
-<member4shared href="#ref-4"/>  
-<member5 href="#ref-5"/>  
-<member6 id="ref-6" xsi:type="SOAP-ENC:string">Hello World</member6>  
-<str1 id="ref-7">hello &#60; world</str1>  
-<str2 id="ref-8">&#60;</str2>  
-<str3 id="ref-9">&#60; world</str3>  
-<str4 href="#ref-7"/>  
-```  
-
- remoting serialization with the `XsdString` option would produce the following XML.  
-
-```  
-<member1 xsi:type="xsd:int">10</member1>  
-<member2 xsi:type="xsd:string">hello</member2>  
-<member3 xsi:type="xsd:string">hello</member3>  
-<member4 href="#ref-3"/>  
-<member4shared href="#ref-3"/>  
-<member5 href="#ref-4"/>  
-<member6 xsi:type="xsd:string">Hello World</member6>  
-<str1 xsi:type="xsd:string">hello &#60; world</str1>  
-<str2 xsi:type="xsd:string">&#60;</str2>  
-<str3 xsi:type="xsd:string">&#60; world</str3>  
-<str4 xsi:type="xsd:string">hello &#60; world</str4>  
-```  
-
- For more information about SOAP envelopes, see www.w3.org/tr/soap/#_Toc478383494.  
-
- ]]></format>
-        </remarks>
+        <summary>Indicates that the output SOAP string type in a SOAP Envelope uses the <see langword="XSD" /> prefix, and that the resulting XML does not have an ID attribute for the string.</summary>
         <forInternalUseOnly />
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>
diff --git a/xml/System.Security.Cryptography.X509Certificates/StoreLocation.xml b/xml/System.Security.Cryptography.X509Certificates/StoreLocation.xml
@@ -31,17 +31,19 @@
     <remarks>
       <format type="text/markdown"><![CDATA[  
 
-## Remarks  
- This enumeration is used with the <xref:System.Security.Cryptography.X509Certificates.X509Store> constructor.  
+## Remarks
+
+This enumeration is used with the <xref:System.Security.Cryptography.X509Certificates.X509Store> constructor.  
 
 
 
-## Examples  
- The following code example opens an X.509 certificate store, adds and deletes certificates, and then closes the store. It assumes you have three certificates to add to and remove from a local store.  
-
- [!code-cpp[x509store2#1](~/samples/snippets/cpp/VS_Snippets_CLR/x509store2/CPP/x509store2.cpp#1)]
- [!code-csharp[x509store2#1](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/x509store2.cs#1)]
- [!code-vb[x509store2#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/x509store2.vb#1)]  
+## Examples
+
+The following example opens an X.509 certificate store, adds and deletes certificates, and then closes the store. It assumes you have three certificates to add to and remove from a local store.  
+
+[!code-cpp[x509store2#1](~/samples/snippets/cpp/VS_Snippets_CLR/x509store2/CPP/x509store2.cpp#1)]
+[!code-csharp[x509store2#1](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/x509store2.cs#1)]
+[!code-vb[x509store2#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/x509store2.vb#1)]  
 
  ]]></format>
     </remarks>
@@ -79,18 +81,6 @@
       <MemberValue>1</MemberValue>
       <Docs>
         <summary>The X.509 certificate store used by the current user.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-
-## Examples  
- The following code example opens an X.509 certificate store, adds and deletes certificates, and then closes the store. It assumes you have three certificates to add to and remove from a local store.  
-
- [!code-cpp[x509store2#1](~/samples/snippets/cpp/VS_Snippets_CLR/x509store2/CPP/x509store2.cpp#1)]
- [!code-csharp[x509store2#1](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/x509store2.cs#1)]
- [!code-vb[x509store2#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/x509store2.vb#1)]  
-
- ]]></format>
-        </remarks>
       </Docs>
     </Member>
     <Member MemberName="LocalMachine">
@@ -125,18 +115,6 @@
       <MemberValue>2</MemberValue>
       <Docs>
         <summary>The X.509 certificate store assigned to the local machine.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-
-## Examples  
- The following code example opens an X.509 certificate store, adds and deletes certificates, and then closes the store. It assumes you have three certificates to add to and remove from a local store.  
-
- [!code-cpp[x509store2#1](~/samples/snippets/cpp/VS_Snippets_CLR/x509store2/CPP/x509store2.cpp#1)]
- [!code-csharp[x509store2#1](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/x509store2.cs#1)]
- [!code-vb[x509store2#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/x509store2.vb#1)]  
-
- ]]></format>
-        </remarks>
       </Docs>
     </Member>
   </Members>

diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanKeyDerivationFunction.xml b/xml/System.Security.Cryptography/ECDiffieHellmanKeyDerivationFunction.xml
@@ -24,9 +24,9 @@
       <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
- The <xref:System.Security.Cryptography.ECDiffieHellmanKeyDerivationFunction> enumeration defines the type of algorithm that will be used to transform a raw secret agreement into key material. The secret agreement is the value that is generated from a private key and the other party's public key, as part of the key exchange. It is the seed value for the key material that is generated by the <xref:System.Security.Cryptography.ECDiffieHellmanCng.DeriveKeyMaterial%2A> method.  
+ The `ECDiffieHellmanKeyDerivationFunction` enumeration defines the type of algorithm that will be used to transform a raw secret agreement into key material. The secret agreement is the value that is generated from a private key and the other party's public key, as part of the key exchange. It is the seed value for the key material that is generated by the <xref:System.Security.Cryptography.ECDiffieHellmanCng.DeriveKeyMaterial%2A?displayProperty=nameWithType> method.  
 
- The <xref:System.Security.Cryptography.ECDiffieHellmanCng.KeyDerivationFunction%2A> property uses this enumeration to get the key derivation function for the <xref:System.Security.Cryptography.ECDiffieHellmanCng> class.  
+ The <xref:System.Security.Cryptography.ECDiffieHellmanCng.KeyDerivationFunction%2A?displayProperty=nameWithType> property uses this enumeration to get the key derivation function for the <xref:System.Security.Cryptography.ECDiffieHellmanCng> class.  
 
  ]]></format>
     </remarks>
@@ -55,17 +55,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>A hash algorithm is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.HashAlgorithm" /> property specifies the name of the algorithm to use. If the algorithm name is not specified, <see cref="T:System.Security.Cryptography.SHA256" /> is used as the default algorithm.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-
-## Remarks  
- You can also specify the <xref:System.Security.Cryptography.ECDiffieHellmanCng.SecretPrepend%2A> and <xref:System.Security.Cryptography.ECDiffieHellmanCng.SecretAppend%2A> properties, but they are not required.  
-
- The amount of key material that is generated is equivalent to the size of the hash value for the specified algorithm.  
-
- ]]></format>
-        </remarks>
+        <summary>A hash algorithm is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.HashAlgorithm" /> property specifies the name of the algorithm to use. If the algorithm name is not specified, <see cref="T:System.Security.Cryptography.SHA256" /> is used as the default algorithm. You can also specify the <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.SecretPrepend" /> and <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.SecretAppend" /> properties, but they are not required. The amount of key material that is generated is equivalent to the size of the hash value for the specified algorithm.</summary>
       </Docs>
     </Member>
     <Member MemberName="Hmac">
@@ -91,17 +81,7 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>A Hash-based Message Authentication Code (HMAC) algorithm is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.HmacKey" /> property specifies the key to use. Either this property must be set or the <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.UseSecretAgreementAsHmacKey" /> property must be set to <see langword="true" />; otherwise, a <see cref="T:System.Security.Cryptography.CryptographicException" /> is thrown when you use <see cref="F:System.Security.Cryptography.ECDiffieHellmanKeyDerivationFunction.Hmac" />. If both properties are set, the secret agreement is used as the HMAC key.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-
-## Remarks  
- You can also specify the <xref:System.Security.Cryptography.ECDiffieHellmanCng.SecretPrepend%2A> and <xref:System.Security.Cryptography.ECDiffieHellmanCng.SecretAppend%2A> properties, but they are not required.  
-
- The amount of key material that is generated is equivalent to the size of the HMAC value.  
-
- ]]></format>
-        </remarks>
+        <summary>A Hash-based Message Authentication Code (HMAC) algorithm is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.HmacKey" /> property specifies the key to use. Either this property must be set or the <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.UseSecretAgreementAsHmacKey" /> property must be set to <see langword="true" />; otherwise, a <see cref="T:System.Security.Cryptography.CryptographicException" /> is thrown when you use <see cref="F:System.Security.Cryptography.ECDiffieHellmanKeyDerivationFunction.Hmac" />. If both properties are set, the secret agreement is used as the HMAC key. You can also specify the <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.SecretPrepend" /> and <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.SecretAppend" /> properties, but they are not required. The amount of key material that is generated is equivalent to the size of the HMAC value.</summary>
       </Docs>
     </Member>
     <Member MemberName="Tls">
@@ -127,16 +107,8 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>The Transport Layer Security (TLS) protocol is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.Seed" /> and <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.Label" /> properties must be set; otherwise, a <see cref="T:System.Security.Cryptography.CryptographicException" /> is thrown when you use <see cref="F:System.Security.Cryptography.ECDiffieHellmanKeyDerivationFunction.Tls" />.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-
-## Remarks  
- This value generates 160 bits of key material.  
-
- ]]></format>
-        </remarks>
+        <summary>The Transport Layer Security (TLS) protocol is used to generate key material. The <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.Seed" /> and <see cref="P:System.Security.Cryptography.ECDiffieHellmanCng.Label" /> properties must be set; otherwise, a <see cref="T:System.Security.Cryptography.CryptographicException" /> is thrown when you use <see cref="F:System.Security.Cryptography.ECDiffieHellmanKeyDerivationFunction.Tls" />. This value generates 160 bits of key material.</summary>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>
diff --git a/xml/System.Security.Cryptography/KeyNumber.xml b/xml/System.Security.Cryptography/KeyNumber.xml
@@ -39,9 +39,7 @@
       <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
- Use the <xref:System.Security.Cryptography.KeyNumber> enumeration with the <xref:System.Security.Cryptography.CspKeyContainerInfo.KeyNumber%2A> property to inspect a key type or with the <xref:System.Security.Cryptography.CspParameters.KeyNumber> field to specify a key type.  
-
-
+ Use the `KeyNumber` enumeration with the <xref:System.Security.Cryptography.CspKeyContainerInfo.KeyNumber%2A?displayProperty=nameWithType> property to inspect a key type or with the <xref:System.Security.Cryptography.CspParameters.KeyNumber?displayProperty=nameWithType> field to specify a key type.   
 
 ## Examples  
  The following code example demonstrates how to use the <xref:System.Security.Cryptography.KeyNumber> enumeration to specify a key type for an <xref:System.Security.Cryptography.RSACryptoServiceProvider> object.  
@@ -84,15 +82,7 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>An exchange key pair used to encrypt session keys so that they can be safely stored and exchanged with other users.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-
-## Remarks  
- This value corresponds to the AT_KEYEXCHANGE value used in the unmanaged Microsoft Cryptographic API (CAPI).  
-
- ]]></format>
-        </remarks>
+        <summary>An exchange key pair used to encrypt session keys so that they can be safely stored and exchanged with other users. This value corresponds to the AT_KEYEXCHANGE value used in the unmanaged Microsoft Cryptographic API (CAPI).</summary>
       </Docs>
     </Member>
     <Member MemberName="Signature">
@@ -125,15 +115,7 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>A signature key pair used for authenticating digitally signed messages or files.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[  
-
-## Remarks  
- This value corresponds to the AT_SIGNATURE value used in the unmanaged Microsoft Cryptographic API (CAPI).  
-
- ]]></format>
-        </remarks>
+        <summary>A signature key pair used for authenticating digitally signed messages or files. This value corresponds to the AT_SIGNATURE value used in the unmanaged Microsoft Cryptographic API (CAPI).</summary>
       </Docs>
     </Member>
   </Members>