Make multi-line elements easier to review

Author: ericstj

xml/System.Buffers/ArrayBufferWriter`1.xml

@@ -387,7 +387,10 @@ This method never returns <xref:System.Span%601.Empty?displayProperty=nameWithTy
       <Parameters />
       <Docs>
         <summary>Resets the data written to the underlying buffer without zeroing its content.</summary>
-        <remarks><para> You must reset or clear the <see cref="T:System.Buffers.ArrayBufferWriter`1" /> before trying to re-use it.</para><para> If you reset the writer using the <see cref="M:System.Buffers.ArrayBufferWriter`1.ResetWrittenCount" /> method, the underlying buffer will not be cleared.</para></remarks>
+        <remarks>
+          <para>You must reset or clear the <see cref="T:System.Buffers.ArrayBufferWriter`1" /> before trying to re-use it.</para>
+          <para>If you reset the writer using the <see cref="M:System.Buffers.ArrayBufferWriter`1.ResetWrittenCount" /> method, the underlying buffer will not be cleared.</para>
+        </remarks>
         <seealso cref="M:System.Buffers.ArrayBufferWriter`1.Clear" />
       </Docs>
     </Member>

xml/System.Diagnostics/Activity.xml

@@ -255,7 +255,11 @@ Callers should either restrict the number of events added to the same `Activity`
         <summary>Add an <see cref="T:System.Diagnostics.ActivityEvent" /> object containing the exception information to the <see cref="P:System.Diagnostics.Activity.Events" /> list.</summary>
         <returns>
           <see langword="this" /> for convenient chaining.</returns>
-        <remarks><para>- The name of the event will be "exception", and it will include the tags "exception.message", "exception.stacktrace", and "exception.type", in addition to the tags provided in the <paramref name="tags" /> parameter.</para><para>- Any registered <see cref="T:System.Diagnostics.ActivityListener" /> with the <see cref="P:System.Diagnostics.ActivityListener.ExceptionRecorder" /> callback will be notified about this exception addition before the <see cref="T:System.Diagnostics.ActivityEvent" /> object is added to the <see cref="P:System.Diagnostics.Activity.Events" /> list.</para><para>- Any registered <see cref="T:System.Diagnostics.ActivityListener" /> with the <see cref="P:System.Diagnostics.ActivityListener.ExceptionRecorder" /> callback that adds "exception.message", "exception.stacktrace", or "exception.type" tags will not have these tags overwritten, except by any subsequent <see cref="T:System.Diagnostics.ActivityListener" /> that explicitly overwrites them.</para></remarks>
+        <remarks>
+          <para>- The name of the event will be "exception", and it will include the tags "exception.message", "exception.stacktrace", and "exception.type", in addition to the tags provided in the <paramref name="tags" /> parameter.</para>
+          <para>- Any registered <see cref="T:System.Diagnostics.ActivityListener" /> with the <see cref="P:System.Diagnostics.ActivityListener.ExceptionRecorder" /> callback will be notified about this exception addition before the <see cref="T:System.Diagnostics.ActivityEvent" /> object is added to the <see cref="P:System.Diagnostics.Activity.Events" /> list.</para>
+          <para>- Any registered <see cref="T:System.Diagnostics.ActivityListener" /> with the <see cref="P:System.Diagnostics.ActivityListener.ExceptionRecorder" /> callback that adds "exception.message", "exception.stacktrace", or "exception.type" tags will not have these tags overwritten, except by any subsequent <see cref="T:System.Diagnostics.ActivityListener" /> that explicitly overwrites them.</para>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="AddLink">

xml/System.Diagnostics/ProcessStartInfo.xml

@@ -1746,7 +1746,11 @@ You can use asynchronous read operations to avoid these dependencies and their d
         <value>
           <see langword="true" /> if the user credentials are only used for network resources; otherwise, <see langword="false" />.
         </value>
-        <remarks><para>This property is referenced if the process is being started by using the user name, password, and domain.</para><para>If the value is <see langword="true" />, the process is started with the caller's identity. The system creates a new logon session with the given credentials, which is used on the network only.</para><para>The system does not validate the specified credentials. Therefore, the process can start, but it may not have access to network resources.</para></remarks>
+        <remarks>
+          <para>This property is referenced if the process is being started by using the user name, password, and domain.</para>
+          <para>If the value is <see langword="true" />, the process is started with the caller's identity. The system creates a new logon session with the given credentials, which is used on the network only.</para>
+          <para>The system does not validate the specified credentials. Therefore, the process can start, but it may not have access to network resources.</para>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="UserName">

xml/System.IO.Compression/ZipFile.xml

@@ -905,10 +905,27 @@ An I/O error occurred while opening a file to be archived.</exception>
         <param name="destinationArchiveFileName">The name of the archive to be created.</param>
         <param name="compressionLevel">The level of the compression (speed/memory vs. compressed size trade-off).</param>
         <param name="includeBaseDirectory">
-          <para>
-            <code>true</code> to indicate that a directory named <code>sourceDirectoryName</code> should be included at the root of the archive. <code>false</code> to indicate that the files and directories in <code>sourceDirectoryName</code> should be included directly in the archive.</para>
+          <para><code>true</code> to indicate that a directory named <code>sourceDirectoryName</code> should be included at the root of the archive. <code>false</code> to indicate that the files and directories in <code>sourceDirectoryName</code> should be included directly in the archive.</para>
+        </param>
+        <param name="entryNameEncoding">
+          <para>The encoding to use when reading or writing entry names and comments in this ZipArchive.</para>
+          <para>NOTE: Specifying this parameter to values other than <see langword="null" /> is discouraged.</para>
+          <para>However, this may be necessary for interoperability with ZIP archive tools and libraries that do not correctly support UTF-8 encoding for entry names or comments.
+            <br /> This value is used as follows while creating the archive:</para>
+          <para>If <code>entryNameEncoding</code> is not specified (<code>== null</code>):</para>
+          <list> 
+            <item>For file names or comments that contain characters outside the ASCII range:
+              <br /> The language encoding flag (EFS) will be set in the general purpose bit flag of the local file header of the corresponding entry, and UTF-8 (<code>Encoding.UTF8</code>) will be used in order to encode the entry name and comment into bytes.</item>
+            <item>For file names or comments that do not contain characters outside the ASCII range:
+              <br /> the language encoding flag (EFS) will not be set in the general purpose bit flag of the local file header of the corresponding entry, and the current system default code page (<code>Encoding.Default</code>) will be used to encode the entry names and comments into bytes.</item>
+          </list>
+          <para>If <code>entryNameEncoding</code> is specified (<code>!= null</code>):</para>
+          <list> 
+            <item>The specified <code>entryNameEncoding</code> will always be used to encode the entry names and comments into bytes.
+              <br />The language encoding flag (EFS) in the general purpose bit flag of the local file header for each entry will be set if and only if the specified <code>entryNameEncoding</code> is a UTF-8 encoding.</item>
+          </list>
+          <para>Note that Unicode encodings other than UTF-8 may not be currently used for the <code>entryNameEncoding</code>, otherwise an <see cref="T:System.ArgumentException" /> is thrown.</para>
         </param>
-        <param name="entryNameEncoding"><para>The encoding to use when reading or writing entry names and comments in this ZipArchive.</para><para>NOTE: Specifying this parameter to values other than <see langword="null" /> is discouraged.</para><para>However, this may be necessary for interoperability with ZIP archive tools and libraries that do not correctly support UTF-8 encoding for entry names or comments.<br /> This value is used as follows while creating the archive:</para><para>If <code>entryNameEncoding</code> is not specified (<code>== null</code>):</para><list> <item>For file names or comments that contain characters outside the ASCII range:<br /> The language encoding flag (EFS) will be set in the general purpose bit flag of the local file header of the corresponding entry, and UTF-8 (<code>Encoding.UTF8</code>) will be used in order to encode the entry name and comment into bytes.</item> <item>For file names or comments that do not contain characters outside the ASCII range:<br /> the language encoding flag (EFS) will not be set in the general purpose bit flag of the local file header of the corresponding entry, and the current system default code page (<code>Encoding.Default</code>) will be used to encode the entry names and comments into bytes.</item> </list><para>If <code>entryNameEncoding</code> is specified (<code>!= null</code>):</para><list> <item>The specified <code>entryNameEncoding</code> will always be used to encode the entry names and comments into bytes.</para><para>The language encoding flag (EFS) in the general purpose bit flag of the local file header for each entry will be set if and only if the specified <code>entryNameEncoding</code> is a UTF-8 encoding.</item> </list><para>Note that Unicode encodings other than UTF-8 may not be currently used for the <code>entryNameEncoding</code>, otherwise an <see cref="T:System.ArgumentException" /> is thrown.</para></param>
         <param name="cancellationToken">The cancellation token to monitor for cancellation requests.</param>
         <summary><para>Asynchronously creates a Zip archive at the path <code>destinationArchiveFileName</code> that contains the files and directories in the directory specified by <code>sourceDirectoryName</code>. The directory structure is preserved in the archive, and a recursive search is done for files to be archived. The archive must not exist. If the directory is empty, an empty archive will be created.</para><para>If a file in the directory cannot be added to the archive, the archive will be left incomplete and invalid and the method will throw an exception. This method optionally includes the base directory in the archive.</para><para>If an error is encountered while adding files to the archive, this method will stop adding files and leave the archive in an invalid state. The paths are permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. If a file in the archive has data in the last write time field that is not a valid Zip timestamp, an indicator value of 1980 January 1 at midnight will be used for the file's last modified time.If an entry with the specified name already exists in the archive, a second entry will be created that has an identical name.Since no <code>CompressionLevel</code> is specified, the default provided by the implementation of the underlying compression algorithm will be used; the <code>ZipArchive</code> will not impose its own default.</para><para>(Currently, the underlying compression algorithm is provided by the <code>System.IO.Compression.DeflateStream</code> class.)</para></summary>
         <returns>To be added.</returns>
@@ -2530,7 +2547,7 @@ An unspecified I/O error occurred while opening the file.</exception>
           <para>If the file exists and is empty or does not exist, a new Zip file will be created.</para>
           <para>Note that creating a Zip file with the <code>ZipArchiveMode.Create</code> mode is more efficient when creating a new Zip file.</para>
         </param>
-        <param name="entryNameEncoding"><para>The encoding to use when reading or writing entry names and comments in this ZipArchive.</para><para>NOTE: Specifying this parameter to values other than <see langword="null" /> is discouraged.</para><para>However, this may be necessary for interoperability with ZIP archive tools and libraries that do not correctly support UTF-8 encoding for entry names or comments.<br /> This value is used as follows:</para><para> <strong>Reading (opening) ZIP archive files:</strong> </para><para>If <code>entryNameEncoding</code> is not specified (<code>== null</code>):</para><list> <item>For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is <em>not</em> set, use the current system default code page (<code>Encoding.Default</code>) in order to decode the entry name and comment.</item> <item>For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header <em>is</em> set, use UTF-8 (<code>Encoding.UTF8</code>) in order to decode the entry name and comment.</item> </list><para>If <code>entryNameEncoding</code> is specified (<code>!= null</code>):</para><list> <item>For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is <em>not</em> set, use the specified <code>entryNameEncoding</code> in order to decode the entry name and comment.</item> <item>For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header <em>is</em> set, use UTF-8 (<code>Encoding.UTF8</code>) in order to decode the entry name and comment.</item> </list><para> <strong>Writing (saving) ZIP archive files:</strong> </para><para>If <code>entryNameEncoding</code> is not specified (<code>== null</code>):</para><list> <item>For entry names or comments that contain characters outside the ASCII range, the language encoding flag (EFS) will be set in the general purpose bit flag of the local file header, and UTF-8 (<code>Encoding.UTF8</code>) will be used in order to encode the entry name and comment into bytes.</item> <item>For entry names or comments that do not contain characters outside the ASCII range, the language encoding flag (EFS) will not be set in the general purpose bit flag of the local file header, and the current system default code page (<code>Encoding.Default</code>) will be used to encode the entry names and comments into bytes.</item> </list><para>If <code>entryNameEncoding</code> is specified (<code>!= null</code>):</para><list> <item>The specified <code>entryNameEncoding</code> will always be used to encode the entry names and comments into bytes.</para><para>The language encoding flag (EFS) in the general purpose bit flag of the local file header will be set if and only if the specified <code>entryNameEncoding</code> is a UTF-8 encoding.</item> </list><para>Note that Unicode encodings other than UTF-8 may not be currently used for the <code>entryNameEncoding</code>, otherwise an <see cref="T:System.ArgumentException" /> is thrown.</para></param>
+        <param name="entryNameEncoding"><para>The encoding to use when reading or writing entry names and comments in this ZipArchive.</para><para>NOTE: Specifying this parameter to values other than <see langword="null" /> is discouraged.</para><para>However, this may be necessary for interoperability with ZIP archive tools and libraries that do not correctly support UTF-8 encoding for entry names or comments.<br /> This value is used as follows:</para><para><strong>Reading (opening) ZIP archive files:</strong> </para><para>If <code>entryNameEncoding</code> is not specified (<code>== null</code>):</para><list> <item>For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is <em>not</em> set, use the current system default code page (<code>Encoding.Default</code>) in order to decode the entry name and comment.</item> <item>For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header <em>is</em> set, use UTF-8 (<code>Encoding.UTF8</code>) in order to decode the entry name and comment.</item> </list><para>If <code>entryNameEncoding</code> is specified (<code>!= null</code>):</para><list> <item>For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is <em>not</em> set, use the specified <code>entryNameEncoding</code> in order to decode the entry name and comment.</item> <item>For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header <em>is</em> set, use UTF-8 (<code>Encoding.UTF8</code>) in order to decode the entry name and comment.</item> </list><para><strong>Writing (saving) ZIP archive files:</strong> </para><para>If <code>entryNameEncoding</code> is not specified (<code>== null</code>):</para><list> <item>For entry names or comments that contain characters outside the ASCII range, the language encoding flag (EFS) will be set in the general purpose bit flag of the local file header, and UTF-8 (<code>Encoding.UTF8</code>) will be used in order to encode the entry name and comment into bytes.</item> <item>For entry names or comments that do not contain characters outside the ASCII range, the language encoding flag (EFS) will not be set in the general purpose bit flag of the local file header, and the current system default code page (<code>Encoding.Default</code>) will be used to encode the entry names and comments into bytes.</item> </list><para>If <code>entryNameEncoding</code> is specified (<code>!= null</code>):</para><list> <item>The specified <code>entryNameEncoding</code> will always be used to encode the entry names and comments into bytes.</para><para>The language encoding flag (EFS) in the general purpose bit flag of the local file header will be set if and only if the specified <code>entryNameEncoding</code> is a UTF-8 encoding.</item> </list><para>Note that Unicode encodings other than UTF-8 may not be currently used for the <code>entryNameEncoding</code>, otherwise an <see cref="T:System.ArgumentException" /> is thrown.</para></param>
         <param name="cancellationToken">The cancellation token to monitor for cancellation requests.</param>
         <summary>Asynchronously opens a <code>ZipArchive</code> on the specified <code>archiveFileName</code> in the specified <code>ZipArchiveMode</code> mode.</summary>
         <returns>To be added.</returns>