RC1 - Update System.Formats.Tar docs (Backport #8375) (#8385)

* Update System.Formats.Tar docs (#8375) * Update tar docs * Apply suggestions from code review * Few more * Update xml/System.Formats.Tar/GnuTarEntry.xml * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Formats.Tar/GnuTarEntry.xml Co-authored-by: Genevieve Warren <[email protected]> * Revert remarks as markdown in TarWriter.WriteEntry/WriteEntryAsync(TarEntry) Co-authored-by: carlossanlop <[email protected]> Co-authored-by: Genevieve Warren <[email protected]> * Apply suggestions from code review * Fix bullet lists * Merge markdowns Co-authored-by: carlossanlop <[email protected]> Co-authored-by: Genevieve Warren <[email protected]>
dotnet · gewarren · Sep 15, 2022 · Sep 12, 2022 · Sep 14, 2022 · Sep 14, 2022
commit db7194e8122752edff782df9519142cc74157eac
diff --git a/xml/System.Formats.Tar/GnuTarEntry.xml b/xml/System.Formats.Tar/GnuTarEntry.xml
@@ -14,16 +14,8 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>Represents a tar entry from an archive of the GNU format.</summary>
-    <remarks>
-      <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-Even though the <xref:System.Formats.Tar.TarEntryFormat.Gnu> format is not POSIX compatible, it implements and supports the Unix-specific fields that were defined in the POSIX IEEE P1003.1 standard from 1988: `devmajor`, `devminor`, `gname`, and `uname`.
-
-      ]]></format>
-    </remarks>
+    <summary>Represents a tar entry in the GNU format.</summary>
+    <remarks>Even though the <see cref="F:System.Formats.Tar.TarEntryFormat.Gnu" /> format is not POSIX compatible, it implements and supports the Unix-specific fields that were defined in the POSIX IEEE P1003.1 standard from 1988: <c>devmajor</c>, <c>devminor</c>, <c>gname</c>, and <c>uname</c>.</remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -45,13 +37,12 @@ Even though the <xref:System.Formats.Tar.TarEntryFormat.Gnu> format is not POSIX
         <param name="other">The <see cref="T:System.Formats.Tar.TarEntry" /> instance to convert to the GNU format.</param>
         <summary>Initializes a new <see cref="T:System.Formats.Tar.GnuTarEntry" /> instance by converting the specified <paramref name="other" /> entry into the GNU format.</summary>
         <remarks>To be added.</remarks>
-        <exception cref="T:System.InvalidOperationException">
+        <exception cref="T:System.ArgumentException">
           <paramref name="other" /> is a <see cref="T:System.Formats.Tar.PaxGlobalExtendedAttributesTarEntry" /> instance.
 
 -or-
 
 The entry type of <paramref name="other" /> is not supported in the GNU format.</exception>
-        <exception cref="T:System.FormatException">The format of <paramref name="other" /> is invalid.</exception>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -74,21 +65,15 @@ The entry type of <paramref name="other" /> is not supported in the GNU format.<
         <param name="entryType">The type of the entry.</param>
         <param name="entryName">A string with the path and file name of this entry.</param>
         <summary>Initializes a new <see cref="T:System.Formats.Tar.GnuTarEntry" /> instance with the specified entry type and entry name.</summary>
-        <remarks>
-          <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-When creating an instance using the <xref:System.Formats.Tar.GnuTarEntry.%23ctor(System.Formats.Tar.TarEntryType,System.String)> constructor, only the following entry types are supported:
+        <remarks>When creating an instance using the <see cref="M:System.Formats.Tar.GnuTarEntry.#ctor(System.Formats.Tar.TarEntryType,System.String)"/> constructor, only the following entry types are supported: <see cref="F:System.Formats.Tar.TarEntryType.Directory"/>, <see cref="F:System.Formats.Tar.TarEntryType.HardLink"/>, <see cref="F:System.Formats.Tar.TarEntryType.SymbolicLink"/>, <see cref="F:System.Formats.Tar.TarEntryType.RegularFile"/>, <see cref="F:System.Formats.Tar.TarEntryType.BlockDevice"/>, <see cref="F:System.Formats.Tar.TarEntryType.CharacterDevice"/>, and <see cref="F:System.Formats.Tar.TarEntryType.Fifo"/>.</remarks>
+        <exception cref="T:System.ArgumentNullException">
+          <paramref name="entryName" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentException">
+          <paramref name="entryName" /> is empty.
 
-- In all platforms: <xref:System.Formats.Tar.TarEntryType.Directory>, <xref:System.Formats.Tar.TarEntryType.HardLink>, <xref:System.Formats.Tar.TarEntryType.SymbolicLink>, <xref:System.Formats.Tar.TarEntryType.RegularFile>.
-- In Unix platforms only: <xref:System.Formats.Tar.TarEntryType.BlockDevice>, <xref:System.Formats.Tar.TarEntryType.CharacterDevice> and <xref:System.Formats.Tar.TarEntryType.Fifo>.
+-or-
 
-          ]]></format>
-        </remarks>
-        <exception cref="T:System.ArgumentException">
-          <paramref name="entryName" /> is <see langword="null" /> or empty.</exception>
-        <exception cref="T:System.InvalidOperationException">The entry type is not supported for creating an entry.</exception>
+The entry type is not supported for creating an entry in the GNU format.</exception>
       </Docs>
     </Member>
     <Member MemberName="AccessTime">
@@ -109,15 +94,7 @@ When creating an instance using the <xref:System.Formats.Tar.GnuTarEntry.%23ctor
       <Docs>
         <summary>A timestamp that represents the last time the file represented by this entry was accessed.</summary>
         <value>To be added.</value>
-        <remarks>
-          <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-In Unix platforms, this timestamp is commonly known as `atime`.
-
-          ]]></format>
-        </remarks>
+        <remarks>In Unix platforms, this timestamp is commonly known as <c>atime</c>.</remarks>
       </Docs>
     </Member>
     <Member MemberName="ChangeTime">
@@ -138,15 +115,7 @@ In Unix platforms, this timestamp is commonly known as `atime`.
       <Docs>
         <summary>A timestamp that represents the last time the metadata of the file represented by this entry was changed.</summary>
         <value>To be added.</value>
-        <remarks>
-          <format type="text/markdown"><![CDATA[
-
-## Remarks
-
-In Unix platforms, this timestamp is commonly known as `ctime`.
-
-          ]]></format>
-        </remarks>
+        <remarks>In Unix platforms, this timestamp is commonly known as <c>ctime</c>.</remarks>
       </Docs>
     </Member>
   </Members>

diff --git a/xml/System.Formats.Tar/PaxGlobalExtendedAttributesTarEntry.xml b/xml/System.Formats.Tar/PaxGlobalExtendedAttributesTarEntry.xml
@@ -14,7 +14,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>Represents a global extended attributes TAR entry from an archive of the PAX format.</summary>
+    <summary>Represents a global extended attributes tar entry of the PAX format.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>

@@ -14,7 +14,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>Represents a tar entry from an archive of the PAX format.</summary>
+    <summary>Represents a tar entry in the PAX format.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -37,13 +37,12 @@
         <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>To be added.</remarks>
-        <exception cref="T:System.InvalidOperationException">
+        <exception cref="T:System.ArgumentException">
           <paramref name="other" /> is a <see cref="T:System.Formats.Tar.PaxGlobalExtendedAttributesTarEntry" /> instance.
 
 -or-
 
 The entry type of <paramref name="other" /> is not supported in the PAX format.</exception>
-        <exception cref="T:System.FormatException">The format of <paramref name="other" /> is invalid.</exception>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -71,33 +70,33 @@ The entry type of <paramref name="other" /> is not supported in the PAX format.<
 
 ## Remarks
 
-When creating an instance using the <xref:System.Formats.Tar.PaxTarEntry.%23ctor(System.Formats.Tar.TarEntryType,System.String)> constructor, only the following entry types are supported:
-
-
-- In all platforms: <xref:System.Formats.Tar.TarEntryType.Directory>, <xref:System.Formats.Tar.TarEntryType.HardLink>, <xref:System.Formats.Tar.TarEntryType.SymbolicLink>, <xref:System.Formats.Tar.TarEntryType.RegularFile>.
-- In Unix platforms only: <xref:System.Formats.Tar.TarEntryType.BlockDevice>, <xref:System.Formats.Tar.TarEntryType.CharacterDevice> and <xref:System.Formats.Tar.TarEntryType.Fifo>.
+When creating an instance using the <xref:System.Formats.Tar.PaxTarEntry.%23ctor(System.Formats.Tar.TarEntryType,System.String)> constructor, only the following entry types are supported: <xref:System.Formats.Tar.TarEntryType.Directory>, <xref:System.Formats.Tar.TarEntryType.HardLink>, <xref:System.Formats.Tar.TarEntryType.SymbolicLink>, <xref:System.Formats.Tar.TarEntryType.RegularFile>, <xref:System.Formats.Tar.TarEntryType.BlockDevice>, <xref:System.Formats.Tar.TarEntryType.CharacterDevice>, and <xref:System.Formats.Tar.TarEntryType.Fifo>.
 
 Use the <xref:System.Formats.Tar.PaxTarEntry.%23ctor(System.Formats.Tar.TarEntryType,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})> constructor to include additional extended attributes when creating the entry.
 
-The following entries are always found in the Extended Attributes dictionary of any PAX entry:
+The following entries are always found in the extended attributes dictionary of any PAX entry:
 
 - Modification time, under the name `mtime`, as a <xref:System.Double> number.
 - Access time, under the name `atime`, as a <xref:System.Double> number.
 - Change time, under the name `ctime`, as a <xref:System.Double> number.
 - Path, under the name `path`, as a string.
 
-The following entries are only found in the Extended Attributes dictionary of a PAX entry if certain conditions are met:
+The following entries are only found in the extended attributes dictionary of a PAX entry if certain conditions are met:
 
 - Group name, under the name `gname`, as a string, if it is larger than 32 bytes.
 - User name, under the name `uname`, as a string, if it is larger than 32 bytes.
 - File length, under the name `size`, as an <xref:System.Int32>, if the string representation of the number is larger than 12 bytes.
 
-
           ]]></format>
         </remarks>
+        <exception cref="T:System.ArgumentNullException">
+          <paramref name="entryName" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentException">
-          <paramref name="entryName" /> is <see langword="null" /> or empty.</exception>
-        <exception cref="T:System.InvalidOperationException">The entry type is not supported for creating an entry.</exception>
+          <paramref name="entryName" /> is empty.
+
+-or-
+
+The entry type is not supported for creating an entry in the PAX format.</exception>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -120,41 +119,38 @@ The following entries are only found in the Extended Attributes dictionary of a
       <Docs>
         <param name="entryType">The type of the entry.</param>
         <param name="entryName">A string with the path and file name of this entry.</param>
-        <param name="extendedAttributes">An enumeration of string key-value pairs that represents the metadata to include in the Extended Attributes entry that precedes the current entry.</param>
-        <summary>Initializes a new <see cref="T:System.Formats.Tar.PaxTarEntry" /> instance with the specified entry type, entry name and Extended Attributes enumeration.</summary>
+        <param name="extendedAttributes">An enumeration of string key-value pairs that represents the metadata to include in the extended attributes entry that precedes the current entry.</param>
+        <summary>Initializes a new <see cref="T:System.Formats.Tar.PaxTarEntry" /> instance with the specified entry type, entry name, and extended attributes enumeration.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-When creating an instance using the <xref:System.Formats.Tar.PaxTarEntry.%23ctor(System.Formats.Tar.TarEntryType,System.String)> constructor, only the following entry types are supported:
+Use this constructor to include additional extended attributes when creating the entry.
 
-- In all platforms: <xref:System.Formats.Tar.TarEntryType.Directory>, <xref:System.Formats.Tar.TarEntryType.HardLink>, <xref:System.Formats.Tar.TarEntryType.SymbolicLink>, <xref:System.Formats.Tar.TarEntryType.RegularFile>.
-- In Unix platforms only: <xref:System.Formats.Tar.TarEntryType.BlockDevice>, <xref:System.Formats.Tar.TarEntryType.CharacterDevice> and <xref:System.Formats.Tar.TarEntryType.Fifo>.
-
-Use the <xref:System.Formats.Tar.PaxTarEntry.%23ctor(System.Formats.Tar.TarEntryType,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})> constructor to include additional extended attributes when creating the entry.
-
-The following entries are always found in the Extended Attributes dictionary of any PAX entry:
+The following entries are always found in the extended attributes dictionary of any PAX entry:
 
 - Modification time, under the name `mtime`, as a <xref:System.Double> number.
 - Access time, under the name `atime`, as a <xref:System.Double> number.
 - Change time, under the name `ctime`, as a <xref:System.Double> number.
 - Path, under the name `path`, as a string.
 
-The following entries are only found in the Extended Attributes dictionary of a PAX entry if certain conditions are met:
+The following entries are only found in the extended attributes dictionary of a PAX entry if certain conditions are met:
 
 - Group name, under the name `gname`, as a string, if it is larger than 32 bytes.
 - User name, under the name `uname`, as a string, if it is larger than 32 bytes.
 - File length, under the name `size`, as an <xref:System.Int32>, if the string representation of the number is larger than 12 bytes.
 
-
           ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
-          <paramref name="extendedAttributes" /> is <see langword="null" />.</exception>
+          <paramref name="extendedAttributes" /> or <paramref name="entryName" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentException">
-          <paramref name="entryName" /> is <see langword="null" /> or empty.</exception>
-        <exception cref="T:System.InvalidOperationException">The entry type is not supported for creating an entry.</exception>
+          <paramref name="entryName" /> is empty.
+
+-or-
+
+The entry type is not supported for creating an entry in the PAX format.</exception>
       </Docs>
     </Member>
     <Member MemberName="ExtendedAttributes">
@@ -181,21 +177,20 @@ The following entries are only found in the Extended Attributes dictionary of a
 ## Remarks
 
 The extended attributes are specified when constructing an entry. Use <xref:System.Formats.Tar.PaxTarEntry.%23ctor(System.Formats.Tar.TarEntryType,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})> to append your own enumeration of extended attributes to the current entry on top of the default ones. Use <xref:System.Formats.Tar.PaxTarEntry.%23ctor(System.Formats.Tar.TarEntryType,System.String)> to only use the default extended attributes.
-            The following entries are always found in the Extended Attributes dictionary of any PAX entry:
 
+The following entries are always found in the extended attributes dictionary of any PAX entry:
 
 - Modification time, under the name `mtime`, as a <xref:System.Double> number.
 - Access time, under the name `atime`, as a <xref:System.Double> number.
 - Change time, under the name `ctime`, as a <xref:System.Double> number.
 - Path, under the name `path`, as a string.
 
-The following entries are only found in the Extended Attributes dictionary of a PAX entry if certain conditions are met:
+The following entries are only found in the extended attributes dictionary of a PAX entry if certain conditions are met:
 
 - Group name, under the name `gname`, as a string, if it is larger than 32 bytes.
 - User name, under the name `uname`, as a string, if it is larger than 32 bytes.
 - File length, under the name `size`, as an <xref:System.Int32>, if the string representation of the number is larger than 12 bytes.
 
-
           ]]></format>
         </remarks>
       </Docs>