 
 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

    private var longLinkNameCounter: UInt
    private var localPaxHeaderCounter: UInt

    public init(fileHandle: FileHandle, force format: TarContainer.Format = .pax) {
        self.handle = fileHandle
        self.format = format

        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 {
