diff --git a/Sources/Containerization/Image/ImageStore/ImageStore+OCILayout.swift b/Sources/Containerization/Image/ImageStore/ImageStore+OCILayout.swift index 45defd79..691021b5 100644 --- a/Sources/Containerization/Image/ImageStore/ImageStore+OCILayout.swift +++ b/Sources/Containerization/Image/ImageStore/ImageStore+OCILayout.swift @@ -25,7 +25,7 @@ extension ImageStore { /// manifests and layer blobs, into a directory structure compliant with the OCI Image Layout specification at the given `out` URL. /// /// - Parameters: - /// - references : A list image references that exists in the `ImageStore` that are to be saved in the OCI Image Layout format. + /// - references: A list image references that exists in the `ImageStore` that are to be saved in the OCI Image Layout format. /// - out: A URL to a directory on disk at which the OCI Image Layout structure will be created. /// - platform: An optional parameter to indicate the platform to be saved for the images. /// Defaults to `nil` signifying that layers for all supported platforms by the images will be saved. @@ -67,7 +67,7 @@ extension ImageStore { /// Imports one or more images and their associated layers from an OCI Image Layout directory. /// /// - Parameters: - /// - from : A URL to a directory on disk at that follows the OCI Image Layout structure. + /// - directory: A URL to a directory on disk at that follows the OCI Image Layout structure. /// - progress: An optional handler over which progress update events about the load operation can be received. /// - Returns: The list of images that were loaded into the `ImageStore`. /// diff --git a/Sources/ContainerizationEXT4/EXT4+Formatter.swift b/Sources/ContainerizationEXT4/EXT4+Formatter.swift index 66b4dbc8..97fdc87e 100644 --- a/Sources/ContainerizationEXT4/EXT4+Formatter.swift +++ b/Sources/ContainerizationEXT4/EXT4+Formatter.swift @@ -22,7 +22,7 @@ import SystemPackage extension EXT4 { /// The `EXT4.Formatter` class provides methods to format a block device with the ext4 filesystem. - /// It allows customization of block size and maximum disk size + /// It allows customization of block size and maximum disk size. public class Formatter { private let blockSize: UInt32 private var size: UInt64 @@ -62,6 +62,7 @@ extension EXT4 { /// - devicePath: The path to the block device where the ext4 filesystem will be created. /// - blockSize: The block size of the ext4 filesystem, specified in bytes. Common values are /// 4096 (4KB) or 1024 (1KB). Default is 4096 (4KB) + /// - minDiskSize: The minimum disk size required for the formatted filesystem. /// /// - Note: This ext4 formatter is designed for creating block devices out of container images and does not support all the /// features and options available in the full ext4 filesystem implementation. It focuses diff --git a/Sources/ContainerizationOCI/Client/RegistryClient+Push.swift b/Sources/ContainerizationOCI/Client/RegistryClient+Push.swift index 2e7affa0..22717856 100644 --- a/Sources/ContainerizationOCI/Client/RegistryClient+Push.swift +++ b/Sources/ContainerizationOCI/Client/RegistryClient+Push.swift @@ -22,10 +22,9 @@ import NIO extension RegistryClient { /// Pushes the content specified by a descriptor to a remote registry. - /// /// - Parameters: /// - name: The namespace which the descriptor should belong under. - /// - ref: The tag or digest for uniquely identifying the manifest. + /// - tag: The tag or digest for uniquely identifying the manifest. /// By convention, any portion that may be a partial or whole digest /// will be proceeded by an `@`. Anything preceding the `@` will be referred /// to as "tag". diff --git a/Sources/ContainerizationOCI/Content/ContentWriter.swift b/Sources/ContainerizationOCI/Content/ContentWriter.swift index 8abfe432..6f2828a4 100644 --- a/Sources/ContainerizationOCI/Content/ContentWriter.swift +++ b/Sources/ContainerizationOCI/Content/ContentWriter.swift @@ -25,10 +25,9 @@ public class ContentWriter { private let encoder = JSONEncoder() /// Create a new ContentWriter. - /// /// - Parameters: - /// - for: The URL to write content to. If this is not a directory a - /// ContainerizationError will be thrown with a code of .internalError. + /// - base: The URL to write content to. If this is not a directory a + /// ContainerizationError will be thrown with a code of .internalError. public init(for base: URL) throws { self.base = base var isDirectory = ObjCBool(true) @@ -52,16 +51,16 @@ public class ContentWriter { /// Reads the data present in the passed in URL and writes it to the base path. /// - Parameters: - /// - from: The URL to read the data from. + /// - url: The URL to read the data from. @discardableResult - public func create(from u: URL) throws -> (size: Int64, digest: SHA256.Digest) { - let data = try Data(contentsOf: u) + public func create(from url: URL) throws -> (size: Int64, digest: SHA256.Digest) { + let data = try Data(contentsOf: url) return try self.write(data) } /// Encodes the passed in type as a JSON blob and writes it to the base path. /// - Parameters: - /// - from: The type to convert to JSON. + /// - content: The type to convert to JSON. @discardableResult public func create(from content: T) throws -> (size: Int64, digest: SHA256.Digest) { let data = try self.encoder.encode(content) diff --git a/Sources/ContainerizationOCI/Platform.swift b/Sources/ContainerizationOCI/Platform.swift index be9f147e..90e8190d 100644 --- a/Sources/ContainerizationOCI/Platform.swift +++ b/Sources/ContainerizationOCI/Platform.swift @@ -39,7 +39,7 @@ public struct Platform: Sendable, Equatable { } } - /// description is the processed value (eg. `linux/arm64/v8`) + /// The computed description, for example, `linux/arm64/v8`. public var description: String { let architecture = architecture if let variant = variant { @@ -48,7 +48,7 @@ public struct Platform: Sendable, Equatable { return "\(os)/\(architecture)" } - /// architecture field specifies the CPU architecture, for example `amd64` or `ppc64`. + /// The CPU architecture, for example, `amd64` or `ppc64`. public var architecture: String { switch _rawArch { case "arm64", "arm", "aarch64", "armhf", "armel": @@ -62,23 +62,23 @@ public struct Platform: Sendable, Equatable { } } - /// os specifies the operating system, for example `linux` or `windows`. + /// The operating system, for example, `linux` or `windows`. public var os: String { _rawOS } - /// osVersion is an optional field specifying the operating system version, for example on Windows `10.0.14393.1066`. + /// An optional field specifying the operating system version, for example on Windows `10.0.14393.1066`. public var osVersion: String? - /// osFeatures is an optional field specifying an array of strings, each listing a required OS feature (for example on Windows `win32k`). + /// An optional field specifying an array of strings, each listing a required OS feature (for example on Windows `win32k`). public var osFeatures: [String]? - /// variant is an optional field specifying a variant of the CPU, for example `v7` to specify ARMv7 when architecture is `arm`. + /// An optional field specifying a variant of the CPU, for example `v7` to specify ARMv7 when architecture is `arm`. public var variant: String? - /// rawOS is the operation system of the image (eg. `linux`) + /// The operation system of the image (eg. `linux`). private let _rawOS: String - /// rawArch is the CPU architecture (eg. `arm64`) + /// The CPU architecture (eg. `arm64`). private let _rawArch: String public init(arch: String, os: String, osVersion: String? = nil, osFeatures: [String]? = nil, variant: String? = nil) { @@ -89,11 +89,11 @@ public struct Platform: Sendable, Equatable { self.variant = variant } - /// Initializes new platform from string + /// Initializes a new platform from a string. /// - Parameters: - /// - from: `string` value representing the platform + /// - platform: A `string` value representing the platform. /// ```swift - /// // create a new ImagePlatform from string + /// // Create a new `ImagePlatform` from string. /// let platform = try Platform(from: "linux/amd64") /// ``` /// ## Throws ## @@ -255,7 +255,7 @@ extension Platform: Hashable { return false } - /// `==` compares if **lhs** and **rhs** are the exact same platforms + /// `==` compares if **lhs** and **rhs** are the exact same platforms. public static func == (lhs: Platform, rhs: Platform) -> Bool { // NOTE: // If the platform struct was created by setting the fields directly and not using (from: String) diff --git a/Sources/ContainerizationOS/Terminal.swift b/Sources/ContainerizationOS/Terminal.swift index 7c5a3294..7fffa558 100644 --- a/Sources/ContainerizationOS/Terminal.swift +++ b/Sources/ContainerizationOS/Terminal.swift @@ -16,8 +16,7 @@ import Foundation -/// `Terminal` provides a clean interface to deal with terminal -/// interactions on Unix platforms. +/// `Terminal` provides a clean interface to deal with terminal interactions on Unix platforms. public struct Terminal: Sendable { private let initState: termios? @@ -40,15 +39,15 @@ public struct Terminal: Sendable { try handle.write(contentsOf: data) } - /// the winsize for a pty + /// The winsize for a pty. public struct Size: Sendable { let size: winsize - /// width or `col` of the pty + /// The width or `col` of the pty. public var width: UInt16 { size.ws_col } - /// height or `rows` of the pty + /// The height or `rows` of the pty. public var height: UInt16 { size.ws_row } @@ -57,13 +56,13 @@ public struct Terminal: Sendable { self.size = size } - /// set the size for use with a pty + /// Set the size for use with a pty. public init(width cols: UInt16, height rows: UInt16) { self.size = winsize(ws_row: rows, ws_col: cols, ws_xpixel: 0, ws_ypixel: 0) } } - /// return the current pty attached to any of the STDIO descriptors + /// Return the current pty attached to any of the STDIO descriptors. public static var current: Terminal { get throws { for i in [STDERR_FILENO, STDOUT_FILENO, STDIN_FILENO] { @@ -75,7 +74,7 @@ public struct Terminal: Sendable { } } - /// the current window size for the pty + /// The current window size for the pty. public var size: Size { get throws { var ws = winsize() @@ -84,9 +83,8 @@ public struct Terminal: Sendable { } } - /// create a new pty pair - /// - /// - Parameter initialSize: initial size of the child pty + /// Create a new pty pair. + /// - Parameter initialSize: An initial size of the child pty. public static func create(initialSize: Size? = nil) throws -> (parent: Terminal, child: Terminal) { var parent: Int32 = 0 var child: Int32 = 0 @@ -117,26 +115,23 @@ extension Terminal { } extension Terminal { - /// resize the current pty from the size of the provided pty - /// - /// - Parameter from: a pty to resize from + /// Resize the current pty from the size of the provided pty. + /// - Parameter pty: A pty to resize from. public func resize(from pty: Terminal) throws { var ws = try pty.size try fromSyscall(ioctl(descriptor, UInt(TIOCSWINSZ), &ws)) } - /// resize the pty to the provided window size - /// - /// - Parameter size: window size for a pty + /// Resize the pty to the provided window size. + /// - Parameter size: A window size for a pty. public func resize(size: Size) throws { var ws = size.size try fromSyscall(ioctl(descriptor, UInt(TIOCSWINSZ), &ws)) } - /// resize the pty to the provided window size - /// - /// - Parameter width: width or cols of the terminal - /// - Parameter height: height or rows of the terminal + /// Resize the pty to the provided window size. + /// - Parameter width: A width or cols of the terminal. + /// - Parameter height: A height or rows of the terminal. public func resize(width: UInt16, height: UInt16) throws { var ws = Size(width: width, height: height) try fromSyscall(ioctl(descriptor, UInt(TIOCSWINSZ), &ws)) @@ -144,7 +139,7 @@ extension Terminal { } extension Terminal { - /// enable raw mode for the pty + /// Enable raw mode for the pty. public func setraw() throws { var attr = try Self.getattr(descriptor) cfmakeraw(&attr) @@ -152,9 +147,8 @@ extension Terminal { try fromSyscall(tcsetattr(descriptor, TCSANOW, &attr)) } - /// enable echo support - /// - /// chars typed WILL be displayed to the term + /// Enable echo support. + /// Chars typed will be displayed to the terminal. public func enableEcho() throws { var attr = try Self.getattr(descriptor) attr.c_iflag &= ~tcflag_t(ICRNL) @@ -162,9 +156,8 @@ extension Terminal { try fromSyscall(tcsetattr(descriptor, TCSANOW, &attr)) } - /// disable echo support - /// - /// chars typed WILL NOT be displayed back to the term + /// Disable echo support. + /// Chars typed will not be displayed back to the terminal. public func disableEcho() throws { var attr = try Self.getattr(descriptor) attr.c_lflag &= ~tcflag_t(ECHO) @@ -178,25 +171,23 @@ extension Terminal { } } -// MARK: reset +// MARK: Reset extension Terminal { - /// close this pty's file descriptor + /// Close this pty's file descriptor. public func close() throws { try fromSyscall(Foundation.close(self.descriptor)) } - /// reset the pty to its initial state + /// Reset the pty to its initial state. public func reset() throws { if var attr = initState { try fromSyscall(tcsetattr(descriptor, TCSANOW, &attr)) } } - /// reset the pty to its initial state masking any errors - /// - /// This is commonly used in a `defer` to reset the current Pty - /// where the error code is not generally useful. + /// Reset the pty to its initial state masking any errors. + /// This is commonly used in a `defer` body to reset the current pty where the error code is not generally useful. public func tryReset() { try? reset() }