Docs: Add missing documentation comments for public declarations

Author: euanh

Plugins/ContainerImageBuilder/runner.swift

@@ -14,6 +14,7 @@
 
 import Foundation
 
+/// Error code returned if the process terminates because of an uncaught signal.
 public enum ExitCode: Error { case rawValue(Int32) }
 
 /// Runs `command` with the given arguments and environment variables, capturing standard output and standard error.

Sources/ContainerRegistry/HTTPClient.swift

@@ -19,7 +19,9 @@ import FoundationNetworking
 import HTTPTypes
 import HTTPTypesFoundation
 
-// HEAD does not include a response body so if an error is thrown, data will be nil
+/// An error encountered while making an HTTP request
+///
+/// The response to a `HEAD` request does not include a body so if an error is thrown, `data` will be `nil`
 public enum HTTPClientError: Error {
     case unexpectedStatusCode(status: HTTPResponse.Status, response: HTTPResponse, data: Data?)
     case unexpectedContentType(String)

Sources/ContainerRegistry/RegistryClient.swift

@@ -19,6 +19,7 @@ import FoundationNetworking
 import HTTPTypes
 import Basics
 
+/// An error encountered while communicating with a container registry.
 public enum RegistryClientError: Error {
     case registryParseError(String)
     case invalidRegistryPath(String)

Sources/ContainerRegistry/Schema.swift

@@ -176,6 +176,7 @@ public struct ImageConfigurationRootFS: Codable, Hashable, Sendable {
         self.diff_ids = diff_ids
     }
 
+    /// Field name mapping
     public enum CodingKeys: String, CodingKey {
         case _type = "type"
         case diff_ids
@@ -400,6 +401,7 @@ public struct Platform: Codable, Hashable, Sendable {
         self.features = features
     }
 
+    /// Field name mapping
     public enum CodingKeys: String, CodingKey {
         case architecture
         case os

Sources/ContainerRegistry/ScratchImage.swift

@@ -27,6 +27,10 @@ public struct ScratchImage {
     var manifestDescriptor: ContentDescriptor
     var index: ImageIndex
 
+    /// Construct a `ScratchImage` structure, representing a scratch container image with no contents.
+    /// - Parameters:
+    ///   - architecture: The CPU architecture encoded in the scratch image layer.   The scratch layer is empty, but this value should match any layers stacked on top of it.
+    ///   - os: The operating system name encoded in the scratch image layer.   The scratch layer is empty, but this value should match any layers stacked on top of it.
     public init(architecture: String, os: String) {
         self.encoder = containerJSONEncoder()
 

Sources/Tar/tar.swift

@@ -242,6 +242,22 @@ public struct TarHeader {
     /// Filename prefix - prepended to name
     var prefix: String = ""
 
+    /// Construct a Tar archive header block
+    /// - Parameters:
+    ///   - name: File name
+    ///   - mode: Access mode
+    ///   - uid: File owner's user ID
+    ///   - gid: File's group ID
+    ///   - size: File size in octets
+    ///   - mtime: Last modification time
+    ///   - typeflag: Type of file represented by this header
+    ///   - linkname: Reference to a previous file in the archive.   Only valid when `typeflag` is `.LNKTYPE`.   This is an internal link in the archive file, _not_ a symbolic link.
+    ///   - uname: File owner's user name
+    ///   - gname: File's group name
+    ///   - devmajor: Device major number.   Only valid when `typeflag` is `.BLKTYPE` or `.CHRTYPE`.
+    ///   - devminor: Device minor number.   Only valid when `typeflag` is `.BLKTYPE` or `.CHRTYPE`.
+    ///   - prefix: Optional filename prefix, allowing file names longer than 100 octets to be stored.
+    /// - Throws: If the value of any field cannot be represented in a Tar header.
     public init(
         name: String,
         mode: Int = 0o555,