diff --git a/Sources/PackageDescription/BuildSettings.swift b/Sources/PackageDescription/BuildSettings.swift index 556f7cde7c0..953d78ee1b4 100644 --- a/Sources/PackageDescription/BuildSettings.swift +++ b/Sources/PackageDescription/BuildSettings.swift @@ -12,6 +12,7 @@ /// The build configuration such as debug or release. public struct BuildConfiguration { + /// The configuration of the build. Valid values are `debug` and `release`. let config: String private init(_ config: String) { @@ -54,7 +55,9 @@ public struct BuildConfiguration { /// ), /// ``` public struct BuildSettingCondition { + /// The applicable platforms for this build setting condition. let platforms: [Platform]? + /// The applicable build configuration for this build setting condition. let config: BuildConfiguration? private init(platforms: [Platform]?, config: BuildConfiguration?) { @@ -113,6 +116,7 @@ struct BuildSettingData { /// A C-language build setting. public struct CSetting { + /// The abstract build setting data. let data: BuildSettingData private init(name: String, value: [String], condition: BuildSettingCondition?) { @@ -182,6 +186,7 @@ public struct CSetting { /// A CXX-language build setting. public struct CXXSetting { + /// The abstract build setting data. let data: BuildSettingData private init(name: String, value: [String], condition: BuildSettingCondition?) { @@ -250,6 +255,7 @@ public struct CXXSetting { /// A Swift language build setting. public struct SwiftSetting { + /// The abstract build setting data. let data: BuildSettingData private init(name: String, value: [String], condition: BuildSettingCondition?) { @@ -306,13 +312,13 @@ public struct SwiftSetting { /// Enable an upcoming feature with the given name. /// - /// An upcoming feature is one that has been accepted into Swift as of a + /// An upcoming feature is one that is available in Swift as of a /// certain language version, but is not available by default in prior /// language modes because it has some impact on source compatibility. /// - /// Multiple upcoming features can be added to a given target, and can - /// be used in a target without affecting its dependencies. An unknown - /// upcoming feature will be ignored by the implementation. + /// You can add multiple upcoming features to a given target, and can + /// use in a target without affecting its dependencies. Targets will ignore any unknown + /// upcoming features. /// /// - Since: First available in PackageDescription 5.8. /// @@ -332,11 +338,11 @@ public struct SwiftSetting { /// Enable an experimental feature with the given name. /// /// An experimental feature is one that is in development, but - /// has not been accepted into Swift as a language feature. + /// is not yet available in Swift as a language feature. /// - /// Multiple experimental features can be added to a given target, and can - /// be used in a target without affecting its dependencies. An unknown - /// experimental feature will be ignored by the implementation. + /// You can add multiple experimental features to a given target, and can + /// use in a target without affecting its dependencies. Targets will ignore any unknown + /// experimental features. /// /// - Since: First available in PackageDescription 5.8. /// @@ -391,6 +397,7 @@ public struct SwiftSetting { /// A linker build setting. public struct LinkerSetting { + /// The abstract build setting data. let data: BuildSettingData private init(name: String, value: [String], condition: BuildSettingCondition?) { diff --git a/Sources/PackageDescription/PackageDescription.swift b/Sources/PackageDescription/PackageDescription.swift index 36f53ff03cd..b6aeece96f8 100644 --- a/Sources/PackageDescription/PackageDescription.swift +++ b/Sources/PackageDescription/PackageDescription.swift @@ -380,6 +380,7 @@ public enum SystemPackageProvider { /// Packages installable by the yum package manager. @available(_PackageDescription, introduced: 5.3) case yumItem([String]) + /// Packages installable by the NuGet package manager. @available(_PackageDescription, introduced: 999.0) case nugetItem([String]) @@ -416,7 +417,7 @@ public enum SystemPackageProvider { } /// Creates a system package provider with a list of installable packages - /// for users of the nuget package manager on Linux or Windows. + /// for users of the NuGet package manager on Linux or Windows. /// /// - Parameter packages: The list of package names. /// diff --git a/Sources/PackageDescription/Resource.swift b/Sources/PackageDescription/Resource.swift index ab3d795eea8..df60a6d8ec7 100644 --- a/Sources/PackageDescription/Resource.swift +++ b/Sources/PackageDescription/Resource.swift @@ -47,7 +47,7 @@ public struct Resource { /// The rule for the resource. let rule: String - + /// The path of the resource. let path: String @@ -97,6 +97,10 @@ public struct Resource { } /// Applies the embed rule to a resource at the given path. + /// + /// You can use the embed rule to embed the contents of the resource into the executable code. + /// - Parameter path: The path for a resource. + /// - Returns: A `Resource` instance. @available(_PackageDescription, introduced: 5.9) public static func embedInCode(_ path: String) -> Resource { return Resource(rule: "embedInCode", path: path, localization: nil) diff --git a/Sources/PackageDescription/SupportedPlatforms.swift b/Sources/PackageDescription/SupportedPlatforms.swift index d643b0a7499..5894c6fa245 100644 --- a/Sources/PackageDescription/SupportedPlatforms.swift +++ b/Sources/PackageDescription/SupportedPlatforms.swift @@ -601,8 +601,11 @@ extension SupportedPlatform { public static let v22: DriverKitVersion = .init(string: "22.0") } + /// A supported custom platform version. public struct CustomPlatformVersion: AppleOSVersion { + /// The name of the custom platform. static var name: String = "custom platform" + /// The minimum valid major version number. static var minimumMajorVersion = 0 fileprivate init(uncheckedVersion version: String) { diff --git a/Sources/PackageDescription/Target.swift b/Sources/PackageDescription/Target.swift index 56645beefb8..20e974efe24 100644 --- a/Sources/PackageDescription/Target.swift +++ b/Sources/PackageDescription/Target.swift @@ -41,10 +41,13 @@ public final class Target { case `macro` } - /// A group a target belongs to that allows customizing access boundaries. A target is treated as - /// a client outside of the package if `excluded`, inside the package boundary if `package`. + /// A group a target belongs to that allows customizing access boundaries. By default, the target belongs + /// to the `package` group, and has access to the symbols inside the package. If the target's group is + /// `excluded`, it is essentially a client of the package. public enum TargetGroup { + /// Treat this target as inside the package boundary. case package + /// Treat this target as outside the package boundary. case excluded } /// The different types of a target's dependency on another entity. @@ -561,7 +564,7 @@ public final class Target { /// /// - Parameters: /// - name: The name of the target. - /// - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside (package by default). + /// - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside. The default value is `package`. /// - dependencies: The dependencies of the target. A dependency can be another target in the package or a product from a package dependency. /// - path: The custom path for the target. By default, the Swift Package Manager requires a target's sources to reside at predefined search paths; /// for example, `[PackageRoot]/Sources/[TargetName]`. @@ -733,7 +736,7 @@ public final class Target { /// /// - Parameters: /// - name: The name of the target. - /// - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside (package by default). + /// - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside. The default value is `package`. /// - dependencies: The dependencies of the target. A dependency can be another target in the package or a product from a package dependency. /// - path: The custom path for the target. By default, the Swift Package Manager requires a target's sources to reside at predefined search paths; /// for example, `[PackageRoot]/Sources/[TargetName]`. @@ -980,7 +983,7 @@ public final class Target { /// /// - Parameters: /// - name: The name of the target. - /// - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside (package by default). + /// - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside. The default value is `package`. /// - dependencies: The dependencies of the target. A dependency can be another target in the package or a product from a package dependency. /// - path: The custom path for the target. By default, the Swift Package Manager requires a target's sources to reside at predefined search paths; /// for example, `[PackageRoot]/Sources/[TargetName]`. @@ -1217,7 +1220,7 @@ public final class Target { /// /// - Parameters: /// - name: The name of the plugin target. - /// - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside (package by default). + /// - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside. The default value is `package`. /// - capability: The type of capability the plugin target provides. /// - dependencies: The plugin target's dependencies. /// - path: The path of the plugin target, relative to the package root. @@ -1412,7 +1415,7 @@ public struct TargetDependencyCondition { extension Target.PluginCapability { - /// Specifies that the plugin provides a build tool capability. + /// The plugin is a build tool. /// /// The plugin will be applied to each target that uses it and should create commands /// that will run before or during the build of the target. @@ -1496,7 +1499,7 @@ public enum PluginPermission { case writeToPackageDirectory(reason: String) } -/// The scope of a network permission. This can be none, local connections only or all connections. +/// The scope of a network permission. This can be none, local connections only, or all connections. @available(_PackageDescription, introduced: 5.9) public enum PluginNetworkPermissionScope { /// Do not allow network access. @@ -1510,7 +1513,7 @@ public enum PluginNetworkPermissionScope { /// Allow connections to any unix domain socket. case unixDomainSocket - /// Allow local and outgoing network connections, limited to a range of allowed ports. + /// Allow local and outgoing network connections, limited to a range of allowed ports. public static func all(ports: Range) -> PluginNetworkPermissionScope { return .all(ports: Array(ports)) }