[docs] Add documentation for TarWriter

Author: tsolomko

Sources/TAR/TarWriter.swift

@@ -5,6 +5,33 @@
 
 import Foundation
 
+/**
+ A type that allows to iteratively create TAR containers with the output being written into a `FileHandle`.
+
+ The `TarWriter` may be helpful in reducing the peak memory usage on certain platforms. However, to achieve this both
+ the creation of TAR entries and the calls to `TarWriter` should be wrapped inside the `autoreleasepool`. Since the
+ `autoreleasepool` is available only on Darwin platforms, the memory reducing effect may be not as significant on
+ non-Darwin platforms (such as Linux or Windows).
+
+ The following code demonstrates an example usage of the `TarWriter`:
+ ```swift
+    let handle: FileHandle = ...
+    let writer = TarWriter(fileHandle: handle)
+    try autoreleasepool {
+        let entry: TarEntry = ...
+        try writer.append(entry)
+    }
+    try writer.finalize()
+    try handle.close()
+ ```
+ Note that `TarWriter.finalize()` must be called after finishing appending entries to the container. However, closing
+ the `FileHandle` remains the responsibility of the caller.
+
+ - Important: Due to the API availability limitations of Foundation's `FileHandle`, on certain platforms errors in
+ `FileHandle` operations may result in unrecoverable runtime failures. As such, it is not recommended to use `TarWriter`
+ on those platforms. The following platforms are _unaffected_ by this issue: macOS 10.15.4+, iOS 13.4+, watchOS 6.2+,
+ tvOS 13.4+.
+ */
 public struct TarWriter {
 
     private let format: TarContainer.Format
@@ -13,6 +40,20 @@ public struct TarWriter {
     private var longLinkNameCounter: UInt
     private var localPaxHeaderCounter: UInt
 
+    /**
+     Creates a new instance for writing TAR entries using the specified `format` into the provided `fileHandle`.
+
+     The `TarWriter` will be forced to use the provided `format`, meaning that certain properties of the `entries` may
+     be missing from the output data if the chosen format does not support corresponding features. The default `.pax`
+     format supports the largest set of features. Other (non-PAX) formats should only be used if you have a specific
+     need for them and you understand limitations of those formats.
+
+     - Parameter fileHandle: A handle into which the output will be written. Note that the `TarWriter` does not
+     close the `fileHandle` and this remains the responsibility of the caller.
+     - Parameter force: Force the usage of the specified format.
+
+     - Important: `TarWriter.finalize()` must be called after all entries have been appended.
+     */
     public init(fileHandle: FileHandle, force format: TarContainer.Format = .pax) {
         self.handle = fileHandle
         self.format = format
@@ -21,6 +62,14 @@ public struct TarWriter {
         self.localPaxHeaderCounter = 0
     }
 
+    /**
+     Adds a new TAR entry at the end of the TAR container.
+
+     On Darwin platforms it is recommended to wrap both the initialization of a `TarEntry` and the call to this
+     function inside the `autoreleasepool` in order to reduce the peak memory usage.
+
+     - Throws: Errors from the `FileHandle` operations.
+     */
     public mutating func append(_ entry: TarEntry) throws {
         var out = Data()
         if format == .gnu {
@@ -70,6 +119,11 @@ public struct TarWriter {
         }
     }
 
+    /**
+     Finalizes the TAR container by adding an EOF marker.
+
+     - Throws: Errors from the `FileHandle` operations.
+     */
     public func finalize() throws {
         // First, we append two 512-byte blocks consisting of zeros as an EOF marker.
         try write(Data(count: 1024))