Address feedback

Author: ericstj

xml/System.Formats.Tar/PaxTarEntry.xml

@@ -48,7 +48,7 @@
       <Docs>
         <param name="other">The <see cref="T:System.Formats.Tar.TarEntry" /> instance to convert to the PAX format.</param>
         <summary>Initializes a new <see cref="T:System.Formats.Tar.PaxTarEntry" /> instance by converting the specified <paramref name="other" /> entry into the PAX format.</summary>
-        <remarks>When converting a <see cref="T:System.Formats.Tar.GnuTarEntry" /> to <see cref="T:System.Formats.Tar.PaxTarEntry" /> using this constructor, the <see cref="P:System.Formats.Tar.GnuTarEntry.AccessTime" /> and <see cref="P:System.Formats.Tar.GnuTarEntry.ChangeTime" /> values will get transfered to the <see cref="P:System.Formats.Tar.PaxTarEntry.ExtendedAttributes" /> dictionary only if their values are not <see langword="default" /> (which is <see cref="F:System.DateTimeOffset.MinValue" />).</remarks>
+        <remarks>When converting a <see cref="T:System.Formats.Tar.GnuTarEntry" /> to <see cref="T:System.Formats.Tar.PaxTarEntry" /> using this constructor, the <see cref="P:System.Formats.Tar.GnuTarEntry.AccessTime" /> and <see cref="P:System.Formats.Tar.GnuTarEntry.ChangeTime" /> values are transferred to the <see cref="P:System.Formats.Tar.PaxTarEntry.ExtendedAttributes" /> dictionary only if their values are not <see langword="default" /> (which is <see cref="F:System.DateTimeOffset.MinValue" />).</remarks>
         <exception cref="T:System.ArgumentException">
           <paramref name="other" /> is a <see cref="T:System.Formats.Tar.PaxGlobalExtendedAttributesTarEntry" /> instance.
 

xml/System.IO.Compression/ZipArchive.xml

@@ -395,30 +395,42 @@ If the comment byte length is larger than <xref:System.UInt16.MaxValue>, it will
         <summary>Asynchronously initializes and returns a new instance of <see cref="T:System.IO.Compression.ZipArchive" /> on the given stream in the specified mode, specifying whether to leave the stream open, with an optional encoding and an optional cancellation token.</summary>
         <returns>To be added.</returns>
         <remarks>
-        <para>Specifying a value for <paramref name="entryNameEncoding" /> other than <see langword="null" /> is discouraged. However, this might be necessary for interoperability with ZIP archive tools and libraries that don't correctly support UTF-8 encoding for entry names.</para>
-        <para>This value is used as follows:</para>
-          <para><strong>Reading (opening) ZIP archive files:</strong></para>
-          <para>If <paramref name="entryNameEncoding" /> is not specified (<c>== null</c>):</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 (<c>Encoding.Default</c>) 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 (<c>Encoding.UTF8</c>) to decode the entry name and comment.</item>
-            </list>
-            <para>If <paramref name="entryNameEncoding" /> is specified (<c>!= null</c>):</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 <paramref name="entryNameEncoding" /> 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 (<c>Encoding.UTF8</c>) to decode the entry name and comment.</item>
-            </list>
-            <para><strong>Writing (saving) ZIP archive files:</strong> </para>
-          <para>If <paramref name="entryNameEncoding" /> is not specified (<c>== null</c>):</para>
-          <list>
-            <item>For entry names and 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 (<c>Encoding.UTF8</c>) will be used to encode the entry name and comment into bytes.</item>
-            <item>For entry names and comments that don't 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 (<c>Encoding.Default</c>) will be used to encode the entry names and comments into bytes.</item>
-          </list>
-          <para>If <paramref name="entryNameEncoding" /> is specified (<c>!= null</c>):</para>
-          <list>
-            <item>The specified <paramref name="entryNameEncoding" /> will always be used to encode the entry names and comments into bytes.</item>
-          </list>
-          <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 <paramref name="entryNameEncoding" /> is a UTF-8 encoding.</para>
+          <para>Specifying a value for <paramref name="entryNameEncoding" /> other than <see langword="null" /> is discouraged. However, this might be necessary for interoperability with ZIP archive tools and libraries that don't correctly support UTF-8 encoding for entry names.</para>
+          <para>This value is used as follows:</para>
+          <dl>
+            <li><strong>Reading (opening) ZIP archive files:</strong>
+              <ul>
+                <li>If <paramref name="entryNameEncoding" /> is not specified (<c>== null</c>):
+                  <ul>
+                    <li>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 (<c>Encoding.Default</c>) to decode the entry name and comment.</li>
+                    <li>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 (<c>Encoding.UTF8</c>) to decode the entry name and comment.</li>
+                  </ul>
+                </li>
+                <li>If <paramref name="entryNameEncoding" /> is specified (<c>!= null</c>):
+                  <ul>
+                    <li>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 <paramref name="entryNameEncoding" /> to decode the entry name and comment.</li>
+                    <li>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 (<c>Encoding.UTF8</c>) to decode the entry name and comment.</li>
+                  </ul>
+                </li>
+              </ul>
+            </li>
+            <li><strong>Writing (saving) ZIP archive files:</strong>
+              <ul>
+                <li>If <paramref name="entryNameEncoding" /> is not specified (<c>== null</c>):
+                  <ul>
+                    <li>For entry names and 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 (<c>Encoding.UTF8</c>) will be used to encode the entry name and comment into bytes.</li>
+                    <li>For entry names and comments that don't 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 (<c>Encoding.Default</c>) will be used to encode the entry names and comments into bytes.</li>
+                  </ul>
+                </li>
+                <li>If <paramref name="entryNameEncoding" /> is specified (<c>!= null</c>):
+                  <ul>
+                    <li>The specified <paramref name="entryNameEncoding" /> will always be used to encode the entry names and comments into bytes.</li>
+                    <li>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 <paramref name="entryNameEncoding" /> is a UTF-8 encoding.</li>
+                  </ul>
+                </li>
+              </ul>
+            </li>
+          </dl>
         </remarks>
         <exception cref="T:System.ArgumentException">
           <para>The stream is already closed.</para>