Continue documenting public surface (#25)

Signed-off-by: Danny Canter <danny_canter@apple.com>

Author: dcantah

README.md

@@ -38,6 +38,15 @@ Applications built using the package will run on macOS Sequoia or later, but the
 
 - Non-isolated container networking - with macOS Sequoia, containers on the same vmnet network cannot communicate with each other
 
+## Example Usage
+
+For examples of how to use some of the libraries surface, the cctl executable is a good start. This tools primary job is as a playground to trial out the API. It contains commands that exercise some of the core functionality of the various products, such as:
+
+1. [Manipulating OCI images](./Sources/cctl/ImageCommand.swift)
+2. [Logging in to container registries](./Sources/cctl/LoginCommand.swift)
+3. [Creating root filesystem blocks](./Sources/cctl/RootfsCommand.swift)
+4. [Running simple Linux containers](./Sources/cctl/RunCommand.swift)
+
 ## Linux kernel
 
 A Linux kernel is required for spawning light weight virtual machines on macOS.

Sources/Containerization/Agent/Vminitd.swift

@@ -42,12 +42,15 @@ public struct Vminitd: Sendable {
         self.client = .init(connection: connection, group: group)
     }
 
+    /// Close the connection to the guest agent.
     public func close() async throws {
         try await client.close()
     }
 }
 
 extension Vminitd: VirtualMachineAgent {
+    /// Perform the standard guest setup necessary for vminitd to be able to
+    /// run containers.
     public func standardSetup() async throws {
         try await up(name: "lo")
 

Sources/Containerization/Container.swift

@@ -17,10 +17,12 @@
 
 /// The core protocol container implementations must implement.
 public protocol Container {
+    /// ID for the container.
     var id: String { get }
-
+    /// The amount of cpus assigned to the container.
     var cpus: Int { get }
+    /// The memory in bytes assigned to the container.
     var memoryInBytes: UInt64 { get }
-
+    /// The network interfaces assigned to the container.
     var interfaces: [any Interface] { get }
 }

Sources/Containerization/DNSConfiguration.swift

@@ -18,11 +18,17 @@
 /// DNS configuration for a container. The values will be used to
 /// construct /etc/resolv.conf for a given container.
 public struct DNS: Sendable {
+    /// The set of default nameservers to use if none are provided
+    /// in the constructor.
     public static let defaultNameservers = ["1.1.1.1"]
 
+    /// The nameservers a container should use.
     public var nameservers: [String]
+    /// The DNS domain to use.
     public var domain: String?
+    /// The DNS search domains to use.
     public var searchDomains: [String]
+    /// The DNS options to use.
     public var options: [String]
 
     public init(

Sources/Containerization/Image/Image.swift

@@ -29,15 +29,19 @@ import ContainerizationExtras
 
 /// Type representing an OCI container image.
 public struct Image: Sendable {
-
     private let contentStore: ContentStore
     /// The description for the image that comprises of its name and a reference to its root descriptor.
     public let description: Description
 
+    /// A description of the OCI image.
     public struct Description: Sendable {
+        /// The string reference of the image.
         public let reference: String
+        /// The descriptor identifying the image.
         public let descriptor: Descriptor
+        /// The digest for the image.
         public var digest: String { descriptor.digest }
+        /// The media type of the image.
         public var mediaType: String { descriptor.mediaType }
 
         public init(reference: String, descriptor: Descriptor) {
@@ -46,9 +50,13 @@ public struct Image: Sendable {
         }
     }
 
+    /// The descriptor for the image.
     public var descriptor: Descriptor { description.descriptor }
+    /// The digest of the image.
     public var digest: String { description.digest }
+    /// The media type of the image.
     public var mediaType: String { description.mediaType }
+    /// The string reference for the image.
     public var reference: String { description.reference }
 
     public init(description: Description, contentStore: ContentStore) {
@@ -79,6 +87,8 @@ public struct Image: Sendable {
         return try content.decode()
     }
 
+    /// Returns the descriptor for the given platform. If it does not exist
+    /// will throw a ContainerizationError with the code set to .invalidArgument.
     public func descriptor(for platform: Platform) async throws -> Descriptor {
         let index = try await self.index()
         let desc = index.manifests.first { $0.platform == platform }

Sources/ContainerizationEXT4/EXT4.swift

@@ -297,6 +297,7 @@ public enum EXT4 {
 }
 
 extension EXT4 {
+    // `EXT4` errors.
     public enum Error: Swift.Error, CustomStringConvertible, Sendable, Equatable {
         case notFound(_ path: String)
         case couldNotReadSuperBlock(_ path: String, _ offset: UInt64, _ size: Int)

Sources/ContainerizationError/ContainerizationError.swift

@@ -20,8 +20,11 @@
 /// Most API surfaces for the core container/process/agent types will
 /// return a ContainerizationError.
 public struct ContainerizationError: Swift.Error, Sendable {
+    /// A code describing the error encountered.
     public var code: Code
+    /// A description of the error.
     public var message: String
+    /// The original error which led to this error being thrown.
     public var cause: (any Error)?
 
     /// Creates a new error.
@@ -48,21 +51,25 @@ public struct ContainerizationError: Swift.Error, Sendable {
         self.cause = cause
     }
 
+    /// Provides a unique hash of the error.
     public func hash(into hasher: inout Hasher) {
         hasher.combine(self.code)
         hasher.combine(self.message)
     }
 
+    /// Equality operator for the error. Uses the code and message.
     public static func == (lhs: Self, rhs: Self) -> Bool {
         lhs.code == rhs.code && lhs.message == rhs.message
     }
 
+    /// Checks if the given error has the provided code.
     public func isCode(_ code: Code) -> Bool {
         self.code == code
     }
 }
 
 extension ContainerizationError: CustomStringConvertible {
+    /// Description of the error.
     public var description: String {
         guard let cause = self.cause else {
             return "\(self.code): \"\(self.message)\""
@@ -72,6 +79,7 @@ extension ContainerizationError: CustomStringConvertible {
 }
 
 extension ContainerizationError {
+    /// Codes for a `ContainerizationError`.
     public struct Code: Sendable, Hashable {
         private enum Value: Hashable, Sendable, CaseIterable {
             case unknown

Sources/ContainerizationExtras/AddressAllocator.swift

@@ -32,6 +32,7 @@ public protocol AddressAllocator<AddressType>: Sendable {
     func disableAllocator() -> Bool
 }
 
+/// Errors that a type implementing AddressAllocator should throw.
 public enum AllocatorError: Swift.Error, CustomStringConvertible, Equatable {
     case allocatorDisabled
     case allocatorFull

Sources/ContainerizationExtras/AsyncLock.swift

@@ -31,6 +31,7 @@ public actor AsyncLock {
 
     public init() {}
 
+    /// withLock provides a scoped locking API to run a function while holding the lock.
     public func withLock<T: Sendable>(_ body: @Sendable @escaping (Context) async throws -> T) async rethrows -> T {
         while self.busy {
             await withCheckedContinuation { cc in

Sources/ContainerizationExtras/FileManager+Temporary.swift

@@ -18,6 +18,7 @@
 import Foundation
 
 extension FileManager {
+    /// Returns a unique temporary directory to use.
     public func uniqueTemporaryDirectory(create: Bool = true) -> URL {
         let tempDirectoryURL = temporaryDirectory
         let uniqueDirectoryURL = tempDirectoryURL.appendingPathComponent(UUID().uuidString)