System.Formats.Tar docs

Author: ericstj

xml/System.Formats.Tar/GnuTarEntry.xml

@@ -48,7 +48,9 @@
       <Docs>
         <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>
+        <remarks>
+          <para>When creating an instance of <see cref="T:System.Formats.Tar.GnuTarEntry" /> using this constructor, if <paramref name="other" /> is <see cref="F:System.Formats.Tar.TarEntryFormat.Gnu" /> or <see cref="F:System.Formats.Tar.TarEntryFormat.Pax" />, then the <see cref="P:System.Formats.Tar.GnuTarEntry.AccessTime" /> and <see cref="P:System.Formats.Tar.GnuTarEntry.ChangeTime" /> properties are set to the same values set in <paramref name="other" />. But if <paramref name="other" /> is of any other format, then <see cref="P:System.Formats.Tar.GnuTarEntry.AccessTime" /> and <see cref="P:System.Formats.Tar.GnuTarEntry.ChangeTime" /> are set to <see langword="default" />, which in the entry header <c>atime</c> and <c>ctime</c> fields is written as <see langword="null" /> bytes. This ensures compatibility with other tools that are unable to read the <c>atime</c> and <c>ctime</c> in <see cref="F:System.Formats.Tar.TarEntryFormat.Gnu" /> entries, as these two fields are not POSIX compatible because other formats expect the <c>prefix</c> field in the same header location where <see cref="F:System.Formats.Tar.TarEntryFormat.Gnu" /> writes <c>atime</c> and <c>ctime</c>.</para>
+        </remarks>
         <exception cref="T:System.ArgumentException">
           <paramref name="other" /> is a <see cref="T:System.Formats.Tar.PaxGlobalExtendedAttributesTarEntry" /> instance.
 

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>To be added.</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 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>
         <exception cref="T:System.ArgumentException">
           <paramref name="other" /> is a <see cref="T:System.Formats.Tar.PaxGlobalExtendedAttributesTarEntry" /> instance.
 

xml/System.Formats.Tar/TarWriter.xml

@@ -85,7 +85,7 @@
         <param name="leaveOpen">
           <see langword="false" /> to dispose the <paramref name="archiveStream" /> when this instance is disposed; <see langword="true" /> to leave the stream open.</param>
         <summary>Initializes a <see cref="T:System.Formats.Tar.TarWriter" /> instance that can write tar entries to the specified stream and optionally leaves the stream open upon disposal of this instance. When using this constructor, the format of the resulting archive is <see cref="F:System.Formats.Tar.TarEntryFormat.Pax" />.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>The <see cref="F:System.Formats.Tar.TarEntryFormat.Pax" /> format is the default format as it is the most flexible and POSIX compatible. This is the only format with which <see cref="T:System.Formats.Tar.TarWriter" /> reads and stores <c>atime</c> and <c>ctime</c> when creating entries from filesystem entries.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="archiveStream" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentException">
@@ -297,7 +297,10 @@ These are the entry types supported for writing on each format:
         <param name="fileName">The path to the file to write to the archive.</param>
         <param name="entryName">The name of the file as it should be represented in the archive. It should include the optional relative path and the filename.</param>
         <summary>Writes the specified file into the archive stream as a tar entry.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <para>The entry will be created using the format specified in the <see cref="M:System.Formats.Tar.TarWriter.#ctor(System.IO.Stream,System.Formats.Tar.TarEntryFormat,System.Boolean)" /> constructor, or will use <see cref="F:System.Formats.Tar.TarEntryFormat.Pax" /> if other constructors are used.</para>
+          <para>If the format is <see cref="F:System.Formats.Tar.TarEntryFormat.Pax" />, the <c>atime</c> and <c>ctime</c> from the file will be stored in the <see cref="P:System.Formats.Tar.PaxTarEntry.ExtendedAttributes" /> dictionary. If the format is <see cref="F:System.Formats.Tar.TarEntryFormat.Gnu" />, this method will not set a value for <see cref="P:System.Formats.Tar.GnuTarEntry.AccessTime" /> and <see cref="P:System.Formats.Tar.GnuTarEntry.ChangeTime" /> because most TAR tools do not support these fields for this format.</para>
+        </remarks>
         <exception cref="T:System.ObjectDisposedException">The archive stream is disposed.</exception>
         <exception cref="T:System.ArgumentException">
           <paramref name="fileName" /> or <paramref name="entryName" /> is <see langword="null" /> or empty.</exception>