From f6292e68b99a781b952f74fc6548f90d654c9a30 Mon Sep 17 00:00:00 2001 From: Benjamin Scholtysik Date: Tue, 18 Jun 2019 14:42:37 -0700 Subject: [PATCH] Update the in-source docs for better readability. --- .../PackageDescription4/BuildSettings.swift | 151 ++++++++------- .../LanguageStandardSettings.swift | 12 +- Sources/PackageDescription4/Package.swift | 181 +++++++++++------- .../PackageDependency.swift | 39 ++-- .../PackageRequirement.swift | 31 +-- Sources/PackageDescription4/Product.swift | 42 ++-- .../SupportedPlatforms.swift | 95 +++++---- Sources/PackageDescription4/Target.swift | 179 +++++++++-------- .../Version+StringLiteralConvertible.swift | 20 ++ Sources/PackageDescription4/Version.swift | 62 +++--- 10 files changed, 460 insertions(+), 352 deletions(-) diff --git a/Sources/PackageDescription4/BuildSettings.swift b/Sources/PackageDescription4/BuildSettings.swift index 5cdcd490e1b..575ed20388a 100644 --- a/Sources/PackageDescription4/BuildSettings.swift +++ b/Sources/PackageDescription4/BuildSettings.swift @@ -8,7 +8,7 @@ See http://swift.org/CONTRIBUTORS.txt for Swift project authors */ -/// The build configuration such as debug or release. +/// The build configuration such as debug or release.. public struct BuildConfiguration: Encodable { private let config: String @@ -23,31 +23,31 @@ public struct BuildConfiguration: Encodable { public static let release: BuildConfiguration = BuildConfiguration("release") } -/// A build setting condition. +/// A condition that limits the application of a build setting. /// -/// By default, build settings will be applicable for all platforms and build -/// configurations. The `.when` modifier can be used to conditionalize a build -/// setting. Invalid usage of `.when` will cause an error to be emitted during -/// manifest parsing. For example, it is invalid to specify a `.when` condition with +/// By default, build settings are applicable for all platforms and build +/// configurations. Use the `.when` modifier to define a build +/// setting for a specific condition. Invalid usage of `.when` emits an error during +/// manifest parsing. For example, it's invalid to specify a `.when` condition with /// both parameters as `nil`. /// -/// Here is an example usage of build setting conditions with various APIs: +/// The following example shows how to use build setting conditions with various APIs: /// -/// ... -/// .target( -/// name: "MyTool", -/// dependencies: ["Utility"], -/// cSettings: [ -/// .headerSearchPath("path/relative/to/my/target"), -/// .define("DISABLE_SOMETHING", .when(platforms: [.iOS], configuration: .release)), -/// ], -/// swiftSettings: [ -/// .define("ENABLE_SOMETHING", .when(configuration: .release)), -/// ], -/// linkerSettings: [ -/// .linkLibrary("openssl", .when(platforms: [.linux])), -/// ] -/// ), +/// ... +/// .target( +/// name: "MyTool", +/// dependencies: ["Utility"], +/// cSettings: [ +/// .headerSearchPath("path/relative/to/my/target"), +/// .define("DISABLE_SOMETHING", .when(platforms: [.iOS], configuration: .release)), +/// ], +/// swiftSettings: [ +/// .define("ENABLE_SOMETHING", .when(configuration: .release)), +/// ], +/// linkerSettings: [ +/// .linkLibrary("openssl", .when(platforms: [.linux])), +/// ] +/// ), public struct BuildSettingCondition: Encodable { private let platforms: [Platform]? @@ -63,8 +63,8 @@ public struct BuildSettingCondition: Encodable { /// At least one parameter is mandatory. /// /// - Parameters: - /// - platforms: The platforms for which this condition will be applied. - /// - configuration: The build configuration for which this condition will be applied. + /// - platforms: The applicable platforms for this build setting condition. + /// - configuration: The applicable build configuration for this build setting condition. public static func when( platforms: [Platform]? = nil, configuration: BuildConfiguration? = nil @@ -84,7 +84,7 @@ fileprivate struct BuildSettingData: Encodable { /// The value of the build setting. let value: [String] - /// A condition which will restrict when the build setting applies. + /// A condition that restricts the application of the build setting. let condition: BuildSettingCondition? } @@ -99,7 +99,7 @@ public struct CSetting: Encodable { /// Provide a header search path relative to the target's directory. /// /// Use this setting to add a search path for headers within your target. - /// Absolute paths are disallowed and this setting can't be used to provide + /// You can't use absolute paths and you can't use this setting to provide /// headers that are visible to other targets. /// /// The path must be a directory inside the package. @@ -107,21 +107,22 @@ public struct CSetting: Encodable { /// - Since: First available in PackageDescription 5.0 /// /// - Parameters: - /// - path: The path of the directory that should be searched for headers. The path is relative to the target's directory. - /// - condition: A condition which will restrict when the build setting applies. + /// - path: The path of the directory that contains the headers. The path is relative to the target's directory. + /// - condition: A condition that restricts the application of the build setting. public static func headerSearchPath(_ path: String, _ condition: BuildSettingCondition? = nil) -> CSetting { return CSetting(name: "headerSearchPath", value: [path], condition: condition) } - /// Defines a value for a macro. If no value is specified, the macro value will - /// be defined as 1. + /// Defines a value for a macro. + /// + /// If you don't specify a value, the macro's default value is 1. /// /// - Since: First available in PackageDescription 5.0 /// /// - Parameters: /// - name: The name of the macro. /// - value: The value of the macro. - /// - condition: A condition which will restrict when the build setting applies. + /// - condition: A condition that restricts the application of the build setting. public static func define(_ name: String, to value: String? = nil, _ condition: BuildSettingCondition? = nil) -> CSetting { var settingValue = name if let value = value { @@ -133,19 +134,19 @@ public struct CSetting: Encodable { /// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool. /// /// As the usage of the word "unsafe" implies, the Swift Package Manager - /// can't safely determine if the build flags will have any negative - /// side-effect to the build since certain flags can change the behavior of + /// can't safely determine if the build flags have any negative + /// side effect on the build since certain flags can change the behavior of /// how a build is performed. /// - /// As some build flags could be exploited for unsupported or malicious + /// As some build flags can be exploited for unsupported or malicious /// behavior, the use of unsafe flags make the products containing this /// target ineligible to be used by other packages. /// /// - Since: First available in PackageDescription 5.0 /// /// - Parameters: - /// - flags: The flags to set. - /// - condition: A condition which will restrict when the build setting applies. + /// - flags: The unsafe flags to set. + /// - condition: A condition that restricts the application of the build setting. public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> CSetting { return CSetting(name: "unsafeFlags", value: flags, condition: condition) } @@ -159,10 +160,10 @@ public struct CXXSetting: Encodable { self.data = BuildSettingData(name: name, value: value, condition: condition) } - /// Provide a header search path relative to the target's root directory. + /// Provide a header search path relative to the target's directory. /// /// Use this setting to add a search path for headers within your target. - /// Absolute paths are disallowed and this setting can't be used to provide + /// You can't use absolute paths and you can't use this setting to provide /// headers that are visible to other targets. /// /// The path must be a directory inside the package. @@ -170,21 +171,22 @@ public struct CXXSetting: Encodable { /// - Since: First available in PackageDescription 5.0 /// /// - Parameters: - /// - path: The path of the directory that should be searched for headers. The path is relative to the target's directory. - /// - condition: A condition which will restrict when the build setting applies. + /// - path: The path of the directory that contains the headers. The path is relative to the target's directory. + /// - condition: A condition that restricts the application of the build setting. public static func headerSearchPath(_ path: String, _ condition: BuildSettingCondition? = nil) -> CXXSetting { return CXXSetting(name: "headerSearchPath", value: [path], condition: condition) } - /// Defines a value for a macro. If no value is specified, the macro value will - /// be defined as 1. + /// Defines a value for a macro. + /// + /// If you don't specify a value, the macro's default value is 1. /// /// - Since: First available in PackageDescription 5.0 /// /// - Parameters: /// - name: The name of the macro. /// - value: The value of the macro. - /// - condition: A condition which will restrict when the build setting applies. + /// - condition: A condition that restricts the application of the build setting. public static func define(_ name: String, to value: String? = nil, _ condition: BuildSettingCondition? = nil) -> CXXSetting { var settingValue = name if let value = value { @@ -196,19 +198,18 @@ public struct CXXSetting: Encodable { /// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool. /// /// As the usage of the word "unsafe" implies, the Swift Package Manager - /// can't safely determine if the build flags will have any negative - /// side-effect to the build since certain flags can change the behavior of + /// can't safely determine if the build flags have any negative + /// side effect on the build since certain flags can change the behavior of /// how a build is performed. /// - /// As some build flags could be exploited for unsupported or malicious - /// behavior, the use of unsafe flags make the products containing this - /// target ineligible to be used by other packages. + /// As some build flags can be exploited for unsupported or malicious + /// behavior, a product can't be used as a dependency in another package if one of its targets uses unsafe flags. /// /// - Since: First available in PackageDescription 5.0 /// /// - Parameters: - /// - flags: The flags to set. - /// - condition: A condition which will restrict when the build setting applies. + /// - flags: The unsafe flags to set. + /// - condition: A condition that restricts the application of the build setting. public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> CXXSetting { return CXXSetting(name: "unsafeFlags", value: flags, condition: condition) } @@ -224,13 +225,13 @@ public struct SwiftSetting: Encodable { /// Define a compilation condition. /// - /// Compilation conditons are used inside to conditionally compile - /// statements. For example, the Swift compiler will only compile the + /// Use compilation conditions to only compile statements if a certain condition is true. + /// For example, the Swift compiler will only compile the /// statements inside the `#if` block when `ENABLE_SOMETHING` is defined: /// - /// #if ENABLE_SOMETHING - /// ... - /// #endif + /// #if ENABLE_SOMETHING + /// ... + /// #endif /// /// Unlike macros in C/C++, compilation conditions don't have an /// associated value. @@ -239,7 +240,7 @@ public struct SwiftSetting: Encodable { /// /// - Parameters: /// - name: The name of the macro. - /// - condition: A condition which will restrict when the build setting applies. + /// - condition: A condition that restricts the application of the build setting. public static func define(_ name: String, _ condition: BuildSettingCondition? = nil) -> SwiftSetting { return SwiftSetting(name: "define", value: [name], condition: condition) } @@ -247,19 +248,18 @@ public struct SwiftSetting: Encodable { /// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool. /// /// As the usage of the word "unsafe" implies, the Swift Package Manager - /// can't safely determine if the build flags will have any negative - /// side-effect to the build since certain flags can change the behavior of + /// can't safely determine if the build flags have any negative + /// side effect on the build since certain flags can change the behavior of /// how a build is performed. /// - /// As some build flags could be exploited for unsupported or malicious - /// behavior, the use of unsafe flags make the products containing this - /// target ineligible to be used by other packages. + /// As some build flags can be exploited for unsupported or malicious + /// behavior, a product can't be used as a dependency in another package if one of its targets uses unsafe flags. /// /// - Since: First available in PackageDescription 5.0 /// /// - Parameters: - /// - flags: The flags to set. - /// - condition: A condition which will restrict when the build setting applies. + /// - flags: The unsafe flags to set. + /// - condition: A condition that restricts the application of the build setting.. public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> SwiftSetting { return SwiftSetting(name: "unsafeFlags", value: flags, condition: condition) } @@ -276,14 +276,14 @@ public struct LinkerSetting: Encodable { /// Declare linkage to a system library. /// /// This setting is most useful when the library can't be linked - /// automatically (for example, C++ based libraries and non-modular - /// libraries). + /// automatically, such as C++ based libraries and non-modular + /// libraries. /// /// - Since: First available in PackageDescription 5.0 /// /// - Parameters: /// - library: The library name. - /// - condition: A condition which will restrict when the build setting applies. + /// - condition: A condition that restricts the application of the build setting. public static func linkedLibrary(_ library: String, _ condition: BuildSettingCondition? = nil) -> LinkerSetting { return LinkerSetting(name: "linkedLibrary", value: [library], condition: condition) } @@ -291,14 +291,14 @@ public struct LinkerSetting: Encodable { /// Declare linkage to a framework. /// /// This setting is most useful when the framework can't be linked - /// automatically (for example, C++ based frameworks and non-modular - /// frameworks). + /// automatically, such as C++ based frameworks and non-modular + /// frameworks. /// /// - Since: First available in PackageDescription 5.0 /// /// - Parameters: /// - framework: The framework name. - /// - condition: A condition which will restrict when the build setting applies. + /// - condition: A condition that restricts the application of the build setting. public static func linkedFramework(_ framework: String, _ condition: BuildSettingCondition? = nil) -> LinkerSetting { return LinkerSetting(name: "linkedFramework", value: [framework], condition: condition) } @@ -306,19 +306,18 @@ public struct LinkerSetting: Encodable { /// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool. /// /// As the usage of the word "unsafe" implies, the Swift Package Manager - /// can't safely determine if the build flags will have any negative - /// side-effect to the build since certain flags can change the behavior of + /// can't safely determine if the build flags have any negative + /// side effect on the build since certain flags can change the behavior of /// how a build is performed. /// - /// As some build flags could be exploited for unsupported or malicious - /// behavior, the use of unsafe flags make the products containing this - /// target ineligible to be used by other packages. + /// As some build flags can be exploited for unsupported or malicious + /// behavior, a product can't be used as a dependency in another package if one of its targets uses unsafe flags. /// /// - Since: First available in PackageDescription 5.0 /// /// - Parameters: - /// - flags: The flags to set. - /// - condition: A condition which will restrict when the build setting applies. + /// - flags: The unsafe flags to set. + /// - condition: A condition that restricts the application of the build setting. public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> LinkerSetting { return LinkerSetting(name: "unsafeFlags", value: flags, condition: condition) } diff --git a/Sources/PackageDescription4/LanguageStandardSettings.swift b/Sources/PackageDescription4/LanguageStandardSettings.swift index 2bf53dc024f..b32904bd949 100644 --- a/Sources/PackageDescription4/LanguageStandardSettings.swift +++ b/Sources/PackageDescription4/LanguageStandardSettings.swift @@ -8,7 +8,7 @@ See http://swift.org/CONTRIBUTORS.txt for Swift project authors */ -/// Support C language standards. +/// The supported C language standard to use for compiling C sources in the package. public enum CLanguageStandard: String, Encodable { case c89 case c90 @@ -24,7 +24,7 @@ public enum CLanguageStandard: String, Encodable { case gnu11 } -/// Supported C++ language standards. +/// The supported C++ language standards to use for compiling C++ sources in the package. public enum CXXLanguageStandard: String, Encodable { case cxx98 = "c++98" case cxx03 = "c++03" @@ -39,8 +39,7 @@ public enum CXXLanguageStandard: String, Encodable { } #if !PACKAGE_DESCRIPTION_4 -/// Represents the version of the Swift language that should be used for -/// compiling Swift sources in the package. +/// The version of the Swift language to use for compiling Swift sources in the package. public enum SwiftVersion { @available(_PackageDescription, introduced: 4, obsoleted: 5) case v3 @@ -54,13 +53,14 @@ public enum SwiftVersion { @available(_PackageDescription, introduced: 5) case v5 - /// User-defined value of Swift version. + /// A user-defined value for the Swift version. /// - /// The value is passed as-is to Swift compiler's `-swift-version` flag. + /// The value is passed as-is to the Swift compiler's `-swift-version` flag. case version(String) } extension SwiftVersion: Encodable { + public func encode(to encoder: Encoder) throws { let value: String diff --git a/Sources/PackageDescription4/Package.swift b/Sources/PackageDescription4/Package.swift index 76bae326531..51463e92860 100644 --- a/Sources/PackageDescription4/Package.swift +++ b/Sources/PackageDescription4/Package.swift @@ -17,19 +17,23 @@ import ucrt #endif import Foundation -/// The `Package` type is used to configure the name, products, targets, -/// dependencies and various other parts of the package. +/// The configuration of a Swift package. +/// +/// Pass configuration options as parameters to your package's initializer +/// statement to provide the name of the package, its targets, products, +/// dependencies, and other configuration options. /// /// By convention, the properties of a `Package` are defined in a single nested -/// initializer statement, and not modified after initialization. For example: +/// initializer statement, and not modified after initialization. The following package manifest shows the initialization +/// of a simple package object for the MyLibrary Swift package: /// -/// // swift-tools-version:5.0 -/// import PackageDesc ription +/// // swift-tools-version:5.1 +/// import PackageDescription /// /// let package = Package( /// name: "MyLibrary", /// platforms: [ -/// .macOS(.v10_14), +/// .macOS(.v10_15), /// ], /// products: [ /// .library(name: "MyLibrary", targets: ["MyLibrary"]), @@ -43,72 +47,81 @@ import Foundation /// ] /// ) /// -/// # About the Swift Tools Version -/// -/// A Package.swift manifest file must begin with the string `// -/// swift-tools-version:` followed by a version number specifier. -/// -/// Examples: +/// A `Package.swift` manifest file must begin with the string `// +/// swift-tools-version:` followed by a version number specifier. The following code listing shows a few examples of valid declarations of the Swift tools version: /// /// // swift-tools-version:3.0.2 /// // swift-tools-version:3.1 /// // swift-tools-version:4.0 /// // swift-tools-version:5.0 +/// // swift-tools-version:5.1 /// /// The Swift tools version declares the version of the `PackageDescription` /// library, the minimum version of the Swift tools and Swift language /// compatibility version to process the manifest, and the minimum version of the /// Swift tools that are needed to use the Swift package. Each version of Swift -/// can introduce updates to the `PackageDescription` library, but the previous +/// can introduce updates to the `PackageDescription` framework, but the previous /// API version will continue to be available to packages which declare a prior /// tools version. This behavior lets you take advantage of new releases of /// Swift, the Swift tools, and the `PackageDescription` library, without having /// to update your package's manifest or losing access to existing packages. public final class Package { + /// A package dependency of a Swift package. + /// /// A package dependency consists of a Git URL to the source of the package, - /// and a requirement for the version of the package that can be used. + /// and a requirement for the version of the package. /// - /// The Swift Package Manager performs a process called dependency resolution to - /// figure out the exact version of the package dependencies that can be used in - /// your package. The results of the dependency resolution are recorded in the - /// `Package.resolved` file which will be placed in the top-level directory of - /// your package. + /// The Swift Package Manager performs a process called *dependency resolution* to + /// figure out the exact version of the package dependencies that an app or other + /// Swift package can use. The `Package.resolved` file records the results of the + /// dependency resolution and lives in the top-level directory of a Swift package. + /// If you add the Swift package as a package dependency to an app for an Apple platform, + /// you can find the `Package.resolved` file inside your `.xcodeproj` or `.xcworkspace`. public class Dependency: Encodable { - /// The dependency requirement can be defined as one of three different version requirements. + /// An enum that represents the requirement for a package dependency. /// - /// 1. Version-based Requirement + /// The dependency requirement can be defined as one of three different version requirements: /// - /// A requirement which restricts what version of a dependency your - /// package can use based on its available versions. When a new package - /// version is published, it should increment the major version component - /// if it has backwards-incompatible changes. It should increment the - /// minor version component if it adds new functionality in - /// a backwards-compatible manner. And it should increment the patch - /// version if it makes backwards-compatible bugfixes. To learn more about - /// the syntax of semantic versioning syntax, see `Version` or visit - /// https://semver.org (https://semver.org/). + /// A version-based requirement /// - /// 2. Branch-based Requirement + /// Decide whether your project accepts updates to a package dependency up + /// to the next major version or up to the next minor version. To be more + /// restrictive, select a specific version range or an exact version. + /// Major versions tend to have more significant changes than minor + /// versions, and may require you to modify your code when they update. + /// The version rule requires Swift packages to conform to semantic + /// versioning. To learn more about the semantic versioning standard, + /// visit [semver.org](https://semver.org). /// - /// Specify the name of a branch that a dependency will follow. This is - /// useful when developing multiple packages which are closely related, - /// allowing you to keep them in sync during development. Note that - /// packages which use branch-based dependency requirements cannot be - /// depended-upon by packages which use version-based dependency + /// Selecting the version requirement is the recommended way to add a package dependency. It allows you to create a balance between restricting changes and obtaining improvements and features. + /// + /// A branch-based requirement + /// + /// Select the name of the branch for your package dependency to follow. + /// Use branch-based dependencies when you're developing multiple packages + /// in tandem or when you don't want to publish versions of your package dependencies. + /// + /// Note that packages which use branch-based dependency requirements + /// can't be added as dependencies to packages that use version-based dependency /// requirements; you should remove branch-based dependency requirements /// before publishing a version of your package. /// - /// 3. Commit-based Requirement + /// A commit-based requirement + /// + /// Select the commit hash for your package dependency to follow. + /// Choosing this option isn't recommended, and should be limited to + /// exceptional cases. While pinning your package dependency to a specific + /// commit ensures that the package dependency doesn't change and your + /// code remains stable, you don't receive any updates at all. If you worry about + /// the stability of a remote package, consider one of the more + /// restrictive options of the version-based requirement. /// - /// A requirement that restricts a dependency to a specific commit - /// hash. This is useful if you want to pin your package to a specific - /// commit hash of a dependency. Note that packages which use - /// commit-based dependency requirements cannot be depended-upon by - /// packages which use version-based dependency requirements; you - /// should remove commit-based dependency requirements before - /// publishing a version of your package. + /// Note that packages which use commit-based dependency requirements + /// can't be added as dependencies to packages that use version-based + /// dependency requirements; you should remove commit-based dependency + /// requirements before publishing a version of your package. public enum Requirement { #if PACKAGE_DESCRIPTION_4 case exactItem(Version) @@ -134,24 +147,24 @@ public final class Package { } } - /// The url of the dependency. + /// The Git url of the package dependency. public let url: String - /// The dependency requirement. + /// The dependency requirement of the package dependency. public let requirement: Requirement - /// Create a dependency. + /// Initializes and returns a newly allocated requirement with the specified url and requirements. init(url: String, requirement: Requirement) { self.url = url self.requirement = requirement } } - /// The name of the package. + /// The name of the Swift package. public var name: String #if !PACKAGE_DESCRIPTION_4 - /// The list of platforms supported by this package. + /// The list of supported platforms with a custom deployment target. @available(_PackageDescription, introduced: 5) public var platforms: [SupportedPlatform]? { get { return _platforms } @@ -160,28 +173,29 @@ public final class Package { #endif private var _platforms: [SupportedPlatform]? - /// pkgconfig name to use for C Modules. If present, swiftpm will try to - /// search for .pc file to get the additional flags needed for the - /// system target. + /// The name to use for C Modules. + /// + /// If present, the Swift Package Manager searches for a `.pc` file + /// to get the required additional flags for a system target. public var pkgConfig: String? - /// Providers array for System target + /// An array of providers for the system target. public var providers: [SystemPackageProvider]? /// The list of targets. public var targets: [Target] - /// The list of products vended by this package. + /// The list of products that this package vends and that can be run or used by its clients. public var products: [Product] - /// The list of dependencies. + /// The list of package dependencies. public var dependencies: [Dependency] #if PACKAGE_DESCRIPTION_4 - /// The list of swift versions, this package is compatible with. + /// The list of Swift versions that this package is compatible with. public var swiftLanguageVersions: [Int]? #else - /// The list of swift versions, this package is compatible with. + /// The list of Swift versions that this package is compatible with. public var swiftLanguageVersions: [SwiftVersion]? #endif @@ -192,7 +206,18 @@ public final class Package { public var cxxLanguageStandard: CXXLanguageStandard? #if PACKAGE_DESCRIPTION_4 - /// Construct a package. + /// Initializes and returns a newly allocated package object with the provided configuration options. + /// + /// - Parameters: + /// - name: The name of the Swift package. + /// - pkgConfig: Additional flags for a system package. + /// - providers: The package providers for a system package. + /// - products: The list of products that this package vends and that can be run or used by its clients. + /// - dependencies: The list of package dependencies. + /// - targets: The list of targets that are part of this package. + /// - swiftLanguageVersions: The list of Swift versions that this package is compatible with. + /// - cLanguageStandard: The C language standard to use for all C targets in this package. + /// - cxxLanguageStandard: The C++ language standard to use for all C++ targets in this package. public init( name: String, pkgConfig: String? = nil, @@ -216,6 +241,16 @@ public final class Package { registerExitHandler() } #else + /// Initializes and returns a newly allocated package object with the provided configuration options. + /// + /// - Parameters: + /// - name: The name of the Swift package. + /// - products: The list of products that this package vends and that can be run or used by its clients. + /// - dependencies: The list of package dependencies. + /// - targets: The list of targets that are part of this package. + /// - swiftLanguageVersions: The list of Swift versions that this package is compatible with. + /// - cLanguageStandard: The C language standard to use for all C targets in this package. + /// - cxxLanguageStandard: The C++ language standard to use for all C++ targets in this package. @available(_PackageDescription, introduced: 4.2, obsoleted: 5) public init( name: String, @@ -240,7 +275,17 @@ public final class Package { registerExitHandler() } - /// Construct a package. + /// Initializes and returns a newly allocated package object with the specified parameters + /// + /// - Parameters: + /// - name: The name of the Swift package. + /// - platforms: The list of minimum deployment targets per platform. + /// - products: The list of products that this package vends and that can be run or used by its clients. + /// - dependencies: The list of package dependencies. + /// - targets: The list of targets that are part of this package. + /// - swiftLanguageVersions: The list of Swift versions that this package is compatible with. + /// - cLanguageStandard: The C language standard to use for all C targets in this package. + /// - cxxLanguageStandard: The C++ language standard to use for all C++ targets in this package. @available(_PackageDescription, introduced: 5) public init( name: String, @@ -269,7 +314,7 @@ public final class Package { #endif private func registerExitHandler() { - // Add custom exit handler to cause package to be dumped at exit, if + // Add a custom exit handler to cause the package to be dumped at exit, if // requested. // // FIXME: This doesn't belong here, but for now is the mechanism we use @@ -283,7 +328,7 @@ public final class Package { } } -/// Represents system package providers. +/// The system package providers used in this Swift package. public enum SystemPackageProvider { #if PACKAGE_DESCRIPTION_4 @@ -294,8 +339,11 @@ public enum SystemPackageProvider { case _aptItem([String]) #endif - /// Declare the list of packages installable using the homebrew package - /// manager on macOS. + /// Declare the list of installable packages using the homebrew package + /// manager on macOS to create a system package provider instance. + /// + /// - Parameters: + /// - packages: The list of package names. public static func brew(_ packages: [String]) -> SystemPackageProvider { #if PACKAGE_DESCRIPTION_4 return .brewItem(packages) @@ -304,8 +352,11 @@ public enum SystemPackageProvider { #endif } - /// Declare the list of packages installable using the apt-get package - /// manager on Ubuntu. + /// Declare the list of installable packages using the apt-get package + /// manager on Ubuntu to create a system package provider instance. + /// + /// - Parameters: + /// - packages: The list of package names. public static func apt(_ packages: [String]) -> SystemPackageProvider { #if PACKAGE_DESCRIPTION_4 return .aptItem(packages) diff --git a/Sources/PackageDescription4/PackageDependency.swift b/Sources/PackageDescription4/PackageDependency.swift index d854309663d..9138068f20a 100644 --- a/Sources/PackageDescription4/PackageDependency.swift +++ b/Sources/PackageDescription4/PackageDependency.swift @@ -10,22 +10,21 @@ extension Package.Dependency { - /// Add a package dependency that is required from the given minimum version, + /// Create a package dependency that uses the version requirement, starting with the given minimum version, /// going up to the next major version. /// - /// This is the recommend way to specify a remote package dependency because - /// it allows you to specify the minimum version you require and gives - /// explicit opt-in for new major versions, but otherwise provides maximal - /// flexibility on which version is used. This helps to prevent conflicts in - /// your package dependency graph. + /// This is the recommended way to specify a remote package dependency. + /// It allows you to specify the minimum version you require, allows updates that include bug fixes + /// and backward-compatible feature updates, but requires you to explicitly update to a new major version of the dependency. + /// This approach provides the maximum flexibility on which version to use, + /// while making sure you don't update to a version with breaking changes, + /// and helps to prevent conflicts in your dependency graph. /// - /// For example, specifying + /// The following example allows the Swift package manager to select a version + /// like a `1.2.3`, `1.2.4`, or `1.3.0`, but not `2.0.0`. /// /// .package(url: "https://example.com/example-package.git", from: "1.2.3"), /// - /// will allow the Swift package manager to select a version like a "1.2.3", - /// "1.2.4" or "1.3.0" but not "2.0.0". - /// /// - Parameters: /// - url: The valid Git URL of the package. /// - version: The minimum version requirement. @@ -50,14 +49,13 @@ extension Package.Dependency { } /// Add a package dependency starting with a specific minimum version, up to - /// but not including a specific maximum version. + /// but not including a specified maximum version. /// - /// For example + /// The following example allows the Swift package manager to pick + /// versions `1.2.3`, `1.2.4`, `1.2.5`, but not `1.2.6`. /// /// .package(url: "https://example.com/example-package.git", "1.2.3"..<"1.2.6"), /// - /// will allow the Swift package manager to pick versions 1.2.3, 1.2.4, 1.2.5, but not 1.2.6. - /// /// - Parameters: /// - url: The valid Git URL of the package. /// - range: The custom version range requirement. @@ -75,12 +73,11 @@ extension Package.Dependency { /// Add a package dependency starting with a specific minimum version, going /// up to and including a specific maximum version. /// - /// For example + /// The following example allows the Swift package manager to pick + /// versions 1.2.3, 1.2.4, 1.2.5, as well as 1.2.6. /// /// .package(url: "https://example.com/example-package.git", "1.2.3"..."1.2.6"), /// - /// will allow the Swift package manager to pick versions 1.2.3, 1.2.4, 1.2.5, as well as 1.2.6. - /// /// - Parameters: /// - url: The valid Git URL of the package. /// - range: The closed version range requirement. @@ -100,10 +97,10 @@ extension Package.Dependency { #if !PACKAGE_DESCRIPTION_4 /// Add a dependency to a local package on the filesystem. /// - /// The package dependency is used as-is and no source control access is - /// performed. Local package dependencies are especially useful during - /// development of a new package or when working on multiple tightly-coupled - /// packages. + /// The Swift Package Manager uses the package dependency as-is + /// and does not perform any source control access. Local package dependencies + /// are especially useful during development of a new package or when working + /// on multiple tightly coupled packages. /// /// - Parameter path: The path of the package. public static func package( diff --git a/Sources/PackageDescription4/PackageRequirement.swift b/Sources/PackageDescription4/PackageRequirement.swift index 1e96a29a2c9..b6f22024388 100644 --- a/Sources/PackageDescription4/PackageRequirement.swift +++ b/Sources/PackageDescription4/PackageRequirement.swift @@ -12,16 +12,17 @@ extension Package.Dependency.Requirement: Encodable { /// Returns a requirement for the given exact version. /// - /// Specifying exact version requirements are usually not recommended, as - /// they can cause conflicts in your package dependency graph when a package - /// is depended on by multiple other packages. + /// Specifying exact version requirements are not recommended as + /// they can cause conflicts in your dependency graph when multiple other packages depend on a package. + /// As Swift packages follow the semantic versioning convention, + /// think about specifying a version range instead. /// - /// Example: + /// The following example defines a version requirement that requires version 1.2.3 of a package. /// /// .exact("1.2.3") /// /// - Parameters: - /// - version: The exact version to be specified. + /// - version: The exact version of the dependency for this requirement. public static func exact(_ version: Version) -> Package.Dependency.Requirement { #if PACKAGE_DESCRIPTION_4 return .exactItem(version) @@ -30,20 +31,19 @@ extension Package.Dependency.Requirement: Encodable { #endif } - /// Returns a requirement for a source control revision. This is usually - /// specified with the hash of a commit. + /// Returns a requirement for a source control revision such as the hash of a commit. /// - /// Note that packages which use commit-based dependency requirements - /// cannot be depended-upon by packages which use version-based dependency + /// Note that packages that use commit-based dependency requirements + /// can't be depended upon by packages that use version-based dependency /// requirements; you should remove commit-based dependency requirements /// before publishing a version of your package. /// - /// Example: + /// The following example defines a version requirement for a specific commit hash. /// /// .revision("e74b07278b926c9ec6f9643455ea00d1ce04a021") /// /// - Parameters: - /// - ref: The Git revision, usually a hash of the commit. + /// - ref: The Git revision, usually a commit hash. public static func revision(_ ref: String) -> Package.Dependency.Requirement { #if PACKAGE_DESCRIPTION_4 return .revisionItem(ref) @@ -54,12 +54,13 @@ extension Package.Dependency.Requirement: Encodable { /// Returns a requirement for a source control branch. /// - /// Note that packages which use branch-based dependency requirements - /// cannot be depended-upon by packages which use version-based dependency + /// Note that packages that use branch-based dependency requirements + /// can't be depended upon by packages that use version-based dependency /// requirements; you should remove branch-based dependency requirements /// before publishing a version of your package. /// - /// Example: + /// The following example defines a version requirement that accepts any + /// change in the develop branch. /// /// .branch("develop") /// @@ -74,7 +75,7 @@ extension Package.Dependency.Requirement: Encodable { } /// Returns a requirement for a version range, starting at the given minimum - /// version and going up to the next major version. + /// version and going up to the next major version. This is the recommended version requirement. /// /// - Parameters: /// - version: The minimum version for the version range. diff --git a/Sources/PackageDescription4/Product.swift b/Sources/PackageDescription4/Product.swift index c1d35d3d783..d40d8ed01f5 100644 --- a/Sources/PackageDescription4/Product.swift +++ b/Sources/PackageDescription4/Product.swift @@ -8,23 +8,23 @@ See http://swift.org/CONTRIBUTORS.txt for Swift project authors */ -/// Defines a package product. +/// The object that defines a package product. /// -/// A package product defines an externally visible build artifact that is +/// A package product defines an externally visible build artifact that's /// available to clients of a package. The product is assembled from the build /// artifacts of one or more of the package's targets. /// /// A package product can be one of two types: /// -/// 1. Library +/// Library /// -/// A library product is used to vend library targets containing the public -/// APIs that will be available to clients. +/// Use a library product to vend library targets. This makes a target's public APIs +/// available to clients that integrate the Swift package. /// -/// 2. Executable +/// Executable /// -/// An executable product is used to vend an executable target. This should -/// only be used if the executable needs to be made available to clients. +/// Use an executable product to vend an executable target. +/// Use this only if you want to make the executable available to clients. /// /// The following example shows a package manifest for a library called "Paper" /// that defines multiple products: @@ -63,14 +63,14 @@ public class Product: Encodable { case type = "product_type" } - /// The name of the product. + /// The name of the package product. public let name: String init(name: String) { self.name = name } - /// Represents an executable product. + /// The executable product of a Swift package. public final class Executable: Product { private enum ExecutableCodingKeys: CodingKey { case targets @@ -93,14 +93,14 @@ public class Product: Encodable { } } - /// Represents a library product. + /// The library product of a Swift package. public final class Library: Product { private enum LibraryCodingKeys: CodingKey { case type case targets } - /// The type of library product. + /// The different types of a library product. public enum LibraryType: String, Encodable { case `static` case `dynamic` @@ -111,7 +111,8 @@ public class Product: Encodable { /// The type of the library. /// - /// If the type is unspecified, package manager will automatically choose a type. + /// If the type is unspecified, the Swift Package Manager automatically + /// chooses a type based on the client's preference. public let type: LibraryType? init(name: String, type: LibraryType? = nil, targets: [String]) { @@ -130,12 +131,13 @@ public class Product: Encodable { } } - /// Create a library product that can be used by clients that depend on this package. + /// Create a library product to allow clients that declare a dependency on this package + /// to use the package's functionality. /// - /// A library's product can either be statically or dynamically linked. It - /// is recommended to not declare the type of library explicitly to let the - /// Swift Package Manager choose between static or dynamic linking depending - /// on the consumer of the package. + /// A library's product can either be statically or dynamically linked. + /// If possible, don't declare the type of library explicitly to let + /// the Swift Package Manager choose between static or dynamic linking based + /// on the preference of the package's consumer. /// /// - Parameters: /// - name: The name of the library product. @@ -151,11 +153,11 @@ public class Product: Encodable { return Library(name: name, type: type, targets: targets) } - /// Create an executable product. + /// Create an executable package product that clients can run. /// /// - Parameters: /// - name: The name of the executable product. - /// - targets: The targets that are bundled into an executable product. + /// - targets: The targets to bundle into an executable product. public static func executable( name: String, targets: [String] diff --git a/Sources/PackageDescription4/SupportedPlatforms.swift b/Sources/PackageDescription4/SupportedPlatforms.swift index 8124b3a86a4..9e8398ddd5e 100644 --- a/Sources/PackageDescription4/SupportedPlatforms.swift +++ b/Sources/PackageDescription4/SupportedPlatforms.swift @@ -8,8 +8,8 @@ See http://swift.org/CONTRIBUTORS.txt for Swift project authors */ -/// Represents a platform that usually corresponds to an operating system such as -/// macOS or Linux. +/// A platform that usually corresponds to an operating system such as +/// iOS, macOS, or Linux. public struct Platform: Encodable { /// The name of the platform. @@ -19,6 +19,7 @@ public struct Platform: Encodable { self.name = name } + /// FIXME: add documentation public static let macOS: Platform = Platform(name: "macos") public static let iOS: Platform = Platform(name: "ios") public static let tvOS: Platform = Platform(name: "tvos") @@ -26,22 +27,22 @@ public struct Platform: Encodable { public static let linux: Platform = Platform(name: "linux") } -/// Represents a platform supported by the package. +/// A platform that the Swift package supports. /// /// By default, the Swift Package Manager assigns a predefined minimum deployment -/// version for each supported platforms unless configured using the `platforms` -/// API. This predefined deployment version will be the oldest deployment target -/// version supported by the installed SDK for a given platform. One exception -/// to this rule is macOS, for which the minimum deployment target version will -/// start from 10.10. Packages can choose to configure the minimum deployment +/// version for each supported platforms unless you configure supported platforms using the `platforms` +/// API. This predefined deployment version is the oldest deployment target +/// version that the installed SDK supports for a given platform. One exception +/// to this rule is macOS, for which the minimum deployment target version +/// starts from 10.10. Packages can choose to configure the minimum deployment /// target version for a platform by using the APIs defined in this struct. The -/// Swift Package Manager will emit appropriate errors when an invalid value is -/// provided for supported platforms, i.e., an empty array, multiple declarations -/// for the same platform or an invalid version specification. +/// Swift Package Manager emits appropriate errors when an invalid value is +/// provided for supported platforms, such as an empty array, multiple declarations +/// for the same platform, or an invalid version specification. /// /// The Swift Package Manager will emit an error if a dependency is not -/// compatible with the top-level package's deployment version; the deployment -/// target of dependencies must be lower than or equal to top-level package's +/// compatible with the top-level package's deployment version. The deployment +/// target of a package's dependencies must be lower than or equal to the top-level package's /// deployment target version for a particular platform. public struct SupportedPlatform: Encodable { @@ -67,14 +68,13 @@ public struct SupportedPlatform: Encodable { } /// Configure the minimum deployment target version for the macOS platform - /// using a custom version string. + /// using a version string. /// - /// The version string must be a series of 2 or 3 dot-separated integers, for - /// example "10.10" or "10.10.1". + /// The version string must be a series of two or three dot-separated integers, such as "10.10" or "10.10.1". /// /// - Since: First available in PackageDescription 5.0 /// - /// - Parameter versionString: The minimum deployment target as a string representation of 2 or 3 dot-separated integers, e.g. "10.10.1". + /// - Parameter versionString: The minimum deployment target as a string representation of two or three dot-separated integers, such as "10.10.1". public static func macOS(_ versionString: String) -> SupportedPlatform { return SupportedPlatform(platform: .macOS, version: SupportedPlatform.MacOSVersion(string: versionString).version) } @@ -91,12 +91,11 @@ public struct SupportedPlatform: Encodable { /// Configure the minimum deployment target version for the iOS platform /// using a custom version string. /// - /// The version string must be a series of 2 or 3 dot-separated integers, for - /// example "8.0" or "8.0.1". + /// The version string must be a series of two or three dot-separated integers, such as "8.0" or "8.0.1". /// /// - Since: First available in PackageDescription 5.0 /// - /// - Parameter versionString: The minimum deployment target as a string representation of 2 or 3 dot-separated integers, e.g. "8.0.1". + /// - Parameter versionString: The minimum deployment target as a string representation of two or three dot-separated integers, such as "8.0.1". public static func iOS(_ versionString: String) -> SupportedPlatform { return SupportedPlatform(platform: .iOS, version: SupportedPlatform.IOSVersion(string: versionString).version) } @@ -113,12 +112,11 @@ public struct SupportedPlatform: Encodable { /// Configure the minimum deployment target version for the tvOS platform /// using a custom version string. /// - /// The version string must be a series of 2 or 3 dot-separated integers, for - /// example "9.0" or "9.0.1". + /// The version string must be a series of two or three dot-separated integers,such as "9.0" or "9.0.1". /// /// - Since: First available in PackageDescription 5.0 /// - /// - Parameter versionString: The minimum deployment target as a string representation of 2 or 3 dot-separated integers, e.g. "9.0.1". + /// - Parameter versionString: The minimum deployment target as a string representation of two or three dot-separated integers, such as "9.0.1". public static func tvOS(_ versionString: String) -> SupportedPlatform { return SupportedPlatform(platform: .tvOS, version: SupportedPlatform.TVOSVersion(string: versionString).version) } @@ -135,18 +133,17 @@ public struct SupportedPlatform: Encodable { /// Configure the minimum deployment target version for the watchOS platform /// using a custom version string. /// - /// The version string must be a series of 2 or 3 dot-separated integers, for - /// example "2.0" or "2.0.1". + /// The version string must be a series of two or three dot-separated integers, such as "2.0" or "2.0.1". /// /// - Since: First available in PackageDescription 5.0 /// - /// - Parameter versionString: The minimum deployment target as a string representation of 2 or 3 dot-separated integers, e.g. "3.0.1". + /// - Parameter versionString: The minimum deployment target as a string representation of two or three dot-separated integers, such as "2.0.1". public static func watchOS(_ versionString: String) -> SupportedPlatform { return SupportedPlatform(platform: .watchOS, version: SupportedPlatform.WatchOSVersion(string: versionString).version) } } -/// Extension to SupportedPlaftorm to define major platform versions. +/// An extension to the SupportedPlatform struct that defines major platform versions. extension SupportedPlatform { /// The macOS version. public struct MacOSVersion: Encodable, AppleOSVersion { @@ -160,32 +157,32 @@ extension SupportedPlatform { self.version = version } - /// macOS 10.10 + /// The value that represents macOS 10.10. /// /// - Since: First available in PackageDescription 5.0 public static let v10_10: MacOSVersion = .init(string: "10.10") - /// macOS 10.11 + /// The value that represents macOS 10.11. /// /// - Since: First available in PackageDescription 5.0 public static let v10_11: MacOSVersion = .init(string: "10.11") - /// macOS 10.12 + /// The value that represents macOS 10.12. /// /// - Since: First available in PackageDescription 5.0 public static let v10_12: MacOSVersion = .init(string: "10.12") - /// macOS 10.13 + /// The value that represents macOS 10.13. /// /// - Since: First available in PackageDescription 5.0 public static let v10_13: MacOSVersion = .init(string: "10.13") - /// macOS 10.14 + /// The value that represents macOS 10.14. /// /// - Since: First available in PackageDescription 5.0 public static let v10_14: MacOSVersion = .init(string: "10.14") - /// macOS 10.15 + /// The value that represents macOS 10.15. /// /// - Since: First available in PackageDescription 5.1 @available(_PackageDescription, introduced: 5.1) @@ -203,27 +200,27 @@ extension SupportedPlatform { self.version = version } - /// tvOS 9.0 + /// The value that represents tvOS 9.0. /// /// - Since: First available in PackageDescription 5.0 public static let v9: TVOSVersion = .init(string: "9.0") - /// tvOS 10.0 + /// The value that represents tvOS 10.0. /// /// - Since: First available in PackageDescription 5.0 public static let v10: TVOSVersion = .init(string: "10.0") - /// tvOS 11.0 + /// The value that represents tvOS 11.0. /// /// - Since: First available in PackageDescription 5.0 public static let v11: TVOSVersion = .init(string: "11.0") - /// tvOS 12.0 + /// The value that represents tvOS 12.0. /// /// - Since: First available in PackageDescription 5.0 public static let v12: TVOSVersion = .init(string: "12.0") - /// tvOS 13.0 + /// The value that represents tvOS 13.0. /// /// - Since: First available in PackageDescription 5.1 @available(_PackageDescription, introduced: 5.1) @@ -241,32 +238,32 @@ extension SupportedPlatform { self.version = version } - /// iOS 8.0 + /// The value that represents iOS 8.0. /// /// - Since: First available in PackageDescription 5.0 public static let v8: IOSVersion = .init(string: "8.0") - /// iOS 9.0 + /// The value that represents iOS 9.0. /// /// - Since: First available in PackageDescription 5.0 public static let v9: IOSVersion = .init(string: "9.0") - /// iOS 10.0 + /// The value that represents iOS 10.0. /// /// - Since: First available in PackageDescription 5.0 public static let v10: IOSVersion = .init(string: "10.0") - /// iOS 11.0 + /// The value that represents iOS 11.0. /// /// - Since: First available in PackageDescription 5.0 public static let v11: IOSVersion = .init(string: "11.0") - /// iOS 12.0 + /// The value that represents iOS 12.0. /// /// - Since: First available in PackageDescription 5.0 public static let v12: IOSVersion = .init(string: "12.0") - /// iOS 13.0 + /// The value that represents iOS 13.0. /// /// - Since: First available in PackageDescription 5.1 @available(_PackageDescription, introduced: 5.1) @@ -284,27 +281,27 @@ extension SupportedPlatform { self.version = version } - /// watchOS 2.0 + /// The value that represents watchOS 2.0. /// /// - Since: First available in PackageDescription 5.0 public static let v2: WatchOSVersion = .init(string: "2.0") - /// watchOS 3.0 + /// The value that represents watchOS 3.0. /// /// - Since: First available in PackageDescription 5.0 public static let v3: WatchOSVersion = .init(string: "3.0") - /// watchOS 4.0 + /// The value that represents watchOS 4.0. /// /// - Since: First available in PackageDescription 5.0 public static let v4: WatchOSVersion = .init(string: "4.0") - /// watchOS 5.0 + /// The value that represents watchOS 5.0. /// /// - Since: First available in PackageDescription 5.0 public static let v5: WatchOSVersion = .init(string: "5.0") - /// watchOS 6.0 + /// The value that represents watchOS 6.0. /// /// - Since: First available in PackageDescription 5.1 @available(_PackageDescription, introduced: 5.1) diff --git a/Sources/PackageDescription4/Target.swift b/Sources/PackageDescription4/Target.swift index f60df6d235e..297c0e13215 100644 --- a/Sources/PackageDescription4/Target.swift +++ b/Sources/PackageDescription4/Target.swift @@ -8,24 +8,22 @@ See http://swift.org/CONTRIBUTORS.txt for Swift project authors */ -/// Targets are the basic building blocks of a package. +/// A target, the basic building block of a Swift package. /// -/// Each target contains a set of source files that are compiled into a module or -/// test suite. Targets can be vended to other packages by defining products that -/// include them. +/// Each target contains a set of source files that are compiled into a module or test suite. +/// You can vend targets to other packages by defining products that include the targets. /// -/// Targets may depend on targets within the same package and on products vended -/// by its package dependencies. +/// A target may depend on other targets within the same package and on products vended by the package's dependencies. public final class Target { - /// The type of this target. + /// The different types of a target. public enum TargetType: String, Encodable { case regular case test case system } - /// Represents a target's dependency on another entity. + /// The different types of a target's dependency on another entity. public enum Dependency { #if PACKAGE_DESCRIPTION_4 case targetItem(name: String) @@ -43,54 +41,59 @@ public final class Target { /// The path of the target, relative to the package root. /// - /// If nil, a directory with the target's name will be searched in the - /// predefined search paths. The predefined search paths are the following - /// directories under the package root: - /// - for regular targets: Sources, Source, src, srcs - /// - for test targets: Tests, Sources, Source, src, srcs + /// If the path is `nil`, the Swift Package Manager looks for a targets source files at predefined search paths + /// and in a subdirectory with the target's name. + /// + /// The predefined search paths are the following directories under the package root: + /// - For regular targets: `Sources`, `Source`, `src`, and `srcs` + /// - For test targets: `Tests`, `Sources`, `Source`, `src`, `srcs` + /// + /// For example, the Swift Package Manager will look for source files inside the `[PackageRoot]/Sources/[TargetName]` directory. + /// + /// Do not escape the package root; that is, values like `../Foo` or `/Foo` are invalid. public var path: String? /// The source files in this target. /// - /// If nil, all valid source files found in the target's path will be included. - /// - /// This can contain directories and individual source files. Directories - /// will be searched recursively for valid source files. + /// If this property is `nil`, all valid source files in the target's path will be included and specified paths are relative to the target path. /// - /// Paths specified are relative to the target path. + /// A path can be a path to a directory or an individual source file. In case of a directory, the Swift Package Manager searches for valid source files + /// recursively inside it. public var sources: [String]? - /// List of paths to be excluded from source inference. + /// The paths you want to exclude from source inference. /// - /// Exclude paths are relative to the target path. - /// This property has more precedence than sources property. + /// Excluded paths are relative to the target path. + /// This property has precedence over the `sources` property. public var exclude: [String] - /// If this is a test target. + /// A boolean value that indicates if this is a test target. public var isTest: Bool { return type == .test } - /// Dependencies on other entities inside or outside the package. + /// The target's dependencies on other entities inside or outside the package. public var dependencies: [Dependency] - /// The path to the directory containing public headers of a C language target. + /// The path to the directory containing public headers of a C-family target. /// - /// If a value is not provided, the directory will be set to "include". + /// If this is `nil`, the directory will be set to `include`. public var publicHeadersPath: String? - /// The type of target. + /// The type of the target. public let type: TargetType - /// `pkgconfig` name to use for system library target. If present, swiftpm will try to - /// search for .pc file to get the additional flags needed for the + /// The `pkgconfig` name to use for a system library target. + /// + /// If present, the Swift Package Manager tries to + /// search for the `.pc` file to get the additional flags needed for the /// system target. public let pkgConfig: String? - /// Providers array for the System library target. + /// The providers array for a system library target. public let providers: [SystemPackageProvider]? - /// C build settings. + /// The target's C build settings. @available(_PackageDescription, introduced: 5) public var cSettings: [CSetting]? { get { return _cSettings } @@ -98,7 +101,7 @@ public final class Target { } private var _cSettings: [CSetting]? - /// C++ build settings. + /// The target's C++ build settings. @available(_PackageDescription, introduced: 5) public var cxxSettings: [CXXSetting]? { get { return _cxxSettings } @@ -106,7 +109,7 @@ public final class Target { } private var _cxxSettings: [CXXSetting]? - /// Swift build settings. + /// The target's Swift build settings. @available(_PackageDescription, introduced: 5) public var swiftSettings: [SwiftSetting]? { get { return _swiftSettings } @@ -114,7 +117,7 @@ public final class Target { } private var _swiftSettings: [SwiftSetting]? - /// Linker build settings. + /// The target's linker settings. @available(_PackageDescription, introduced: 5) public var linkerSettings: [LinkerSetting]? { get { return _linkerSettings } @@ -161,20 +164,23 @@ public final class Target { /// Create a library or executable target. /// - /// A target can either contain Swift or C-family source files. You cannot + /// A target can either contain Swift or C-family source files and you can't /// mix Swift and C-family source files within a target. A target is /// considered to be an executable target if there is a `main.swift`, - /// `main.m`, `main.c` or `main.cpp` file in the target's directory. All + /// `main.m`, `main.c`, or `main.cpp` file in the target's directory. All /// other targets are considered to be library targets. /// /// - Parameters: /// - name: The name of the target. - /// - dependencies: The dependencies of the target. These can either be other targets in the package or products from package dependencies. - /// - path: The custom path for the target. By default, targets will be looked up in the /Sources/ directory. - /// Do not escape the package root, i.e. values like "../Foo" or "/Foo" are invalid. - /// - exclude: A list of paths to exclude from being considered source files. This path is relative to the target's directory. - /// - sources: An explicit list of source files. - /// - publicHeadersPath: The directory containing public headers of a C-family family library target. + /// - 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, a targets sources are expected to be located in the predefined search paths, + /// such as `[PackageRoot]/Sources/[TargetName]`. + /// Do not escape the package root; that is, values like `../Foo` or `/Foo` are invalid. + /// - exclude: A list of paths to files or directories that should not be considered source files. This path is relative to the target's directory. + /// This parameter has precedence over the `sources` parameter. + /// - sources: An explicit list of source files. In case of a directory, the Swift Package Manager searches for valid source files + /// recursively. + /// - publicHeadersPath: The path to the directory containing public headers of a C-family target. @available(_PackageDescription, introduced: 4, obsoleted: 5) public static func target( name: String, @@ -197,19 +203,22 @@ public final class Target { /// Create a library or executable target. /// - /// A target can either contain Swift or C-family source files. You cannot + /// A target can either contain Swift or C-family source files. You can't /// mix Swift and C-family source files within a target. A target is /// considered to be an executable target if there is a `main.swift`, - /// `main.m`, `main.c` or `main.cpp` file in the target's directory. All + /// `main.m`, `main.c`, or `main.cpp` file in the target's directory. All /// other targets are considered to be library targets. /// /// - Parameters: /// - name: The name of the target. - /// - dependencies: The dependencies of the target. These can either be other targets in the package or products from package dependencies. - /// - path: The custom path for the target. By default, targets will be looked up in the /Sources/ directory. - /// Do not escape the package root, i.e. values like "../Foo" or "/Foo" are invalid. - /// - exclude: A list of paths to exclude from being considered source files. This path is relative to the target's directory. - /// - sources: An explicit list of source files. + /// - 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, a targets sources are expected to be located in the predefined search paths, + /// such as `[PackageRoot]/Sources/[TargetName]`. + /// Do not escape the package root; that is, values like `../Foo` or `/Foo` are invalid.. + /// - exclude: A list of paths to files or directories that should not be considered source files. This path is relative to the target's directory. + /// This parameter has precedence over the `sources` parameter. + /// - sources: An explicit list of source files. In case of a directory, the Swift Package Manager searches for valid source files + /// recursively. /// - publicHeadersPath: The directory containing public headers of a C-family family library target. /// - cSettings: The C settings for this target. /// - cxxSettings: The C++ settings for this target. @@ -245,16 +254,19 @@ public final class Target { /// Create a test target. /// - /// Test targets are written using the XCTest testing framework. Test targets - /// generally declare target dependency on the targets they test. + /// Write test targets using the XCTest testing framework. + /// Test targets generally declare a dependency on the targets they test. /// /// - Parameters: /// - name: The name of the target. - /// - dependencies: The dependencies of the target. These can either be other targets in the package or products from other packages. - /// - path: The custom path for the target. By default, targets will be looked up in the /Sources/ directory. - /// Do not escape the package root, i.e. values like "../Foo" or "/Foo" are invalid. - /// - exclude: A list of paths to exclude from being considered source files. This path is relative to the target's directory. - /// - sources: An explicit list of source files. + /// - 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, a targets sources are expected to be located in the predefined search paths, + /// such as `[PackageRoot]/Sources/[TargetName]`. + /// Do not escape the package root; that is, values like `../Foo` or `/Foo` are invalid. + /// - exclude: A list of paths to files or directories that should not be considered source files. This path is relative to the target's directory. + /// This parameter has precedence over the `sources` parameter. + /// - sources: An explicit list of source files. In case of a directory, the Swift Package Manager searches for valid source files + /// recursively. @available(_PackageDescription, introduced: 4, obsoleted: 5) public static func testTarget( name: String, @@ -276,16 +288,19 @@ public final class Target { /// Create a test target. /// - /// Test targets are written using the XCTest testing framework. Test targets - /// generally declare target dependency on the targets they test. + /// Write test targets using the XCTest testing framework. + /// Test targets generally declare a dependency on the targets they test. /// /// - Parameters: /// - name: The name of the target. - /// - dependencies: The dependencies of the target. These can either be other targets in the package or products from other packages. - /// - path: The custom path for the target. By default, targets will be looked up in the /Sources/ directory. - /// Do not escape the package root, i.e. values like "../Foo" or "/Foo" are invalid. - /// - exclude: A list of paths to exclude from being considered source files. This path is relative to the target's directory. - /// - sources: An explicit list of source files. + /// - 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, a targets sources are expected to be located in the predefined search paths, + /// such as `[PackageRoot]/Sources/[TargetName]`. + /// Do not escape the package root; that is, values like `../Foo` or `/Foo` are invalid. + /// - exclude: A list of paths to files or directories that should not be considered source files. This path is relative to the target's directory. + /// This parameter has precedence over the `sources` parameter. + /// - sources: An explicit list of source files. In case of a directory, the Swift Package Manager searches for valid source files + /// recursively. /// - cSettings: The C settings for this target. /// - cxxSettings: The C++ settings for this target. /// - swiftSettings: The Swift settings for this target. @@ -320,18 +335,17 @@ public final class Target { #if !PACKAGE_DESCRIPTION_4 /// Create a system library target. - /// - /// System library targets are used to adapt a library installed on the system to - /// work with Swift packages. Such libraries are generally installed by system - /// package managers (such as Homebrew and APT) and exposed to Swift packages by - /// providing a modulemap file along with other metadata such as the library's - /// pkg-config name. + /// + /// Use system library targets to adapt a library installed on the system to work with Swift packages. + /// Such libraries are generally installed by system package managers (such as Homebrew and apt-get) + /// and exposed to Swift packages by providing a `modulemap` file along with other metadata such as the library's `pkgConfig` name. /// /// - Parameters: /// - name: The name of the target. - /// - path: The custom path for the target. By default, targets will be looked up in the /Sources/ directory. - /// Do not escape the package root, i.e. values like "../Foo" or "/Foo" are invalid. - /// - pkgConfig: The name of the pkg-config file for this system library. + /// - path: The custom path for the target. By default, a targets sources are expected to be located in the predefined search paths, + /// such as `[PackageRoot]/Sources/[TargetName]`. + /// Do not escape the package root; that is, values like `../Foo` or `/Foo` are invalid. + /// - pkgConfig: The name of the `pkg-config` file for this system library. /// - providers: The providers for this system library. public static func systemLibrary( name: String, @@ -402,7 +416,10 @@ extension Target: Encodable { } extension Target.Dependency { - /// A dependency on a target in the same package. + /// Creates a dependency on a target in the same package. + /// + /// - parameters: + /// - name: The name of the target. public static func target(name: String) -> Target.Dependency { #if PACKAGE_DESCRIPTION_4 return .targetItem(name: name) @@ -411,7 +428,11 @@ extension Target.Dependency { #endif } - /// A dependency on a product from a package dependency. + /// Creates a dependency on a product from a package dependency. + /// + /// - parameters: + /// - name: The name of the product. + /// - package: The name of the package. public static func product(name: String, package: String? = nil) -> Target.Dependency { #if PACKAGE_DESCRIPTION_4 return .productItem(name: name, package: package) @@ -420,8 +441,11 @@ extension Target.Dependency { #endif } - // A by-name dependency that resolves to either a target or a product, - // as above, after the package graph has been loaded. + /// Creates a by-name dependency that resolves to either a target or a product but + /// after the package graph has been loaded. + /// + /// - parameters: + /// - name: The name of the dependency, either a target or a product. public static func byName(name: String) -> Target.Dependency { #if PACKAGE_DESCRIPTION_4 return .byNameItem(name: name) @@ -434,6 +458,11 @@ extension Target.Dependency { // MARK: ExpressibleByStringLiteral extension Target.Dependency: ExpressibleByStringLiteral { + + /// Creates a target dependency instance with the given value. + /// + /// - parameters: + /// - value: A string literal. public init(stringLiteral value: String) { #if PACKAGE_DESCRIPTION_4 self = .byNameItem(name: value) diff --git a/Sources/PackageDescription4/Version+StringLiteralConvertible.swift b/Sources/PackageDescription4/Version+StringLiteralConvertible.swift index 7aeecee4784..fb5e0fb7df0 100644 --- a/Sources/PackageDescription4/Version+StringLiteralConvertible.swift +++ b/Sources/PackageDescription4/Version+StringLiteralConvertible.swift @@ -10,6 +10,10 @@ extension Version: ExpressibleByStringLiteral { + /// Initializes and returns a newly allocated version struct for the provided string literal. + /// + /// - Parameters: + /// - version: A string literal to use for creating a new version object. public init(stringLiteral value: String) { if let version = Version(value) { self.init(version) @@ -23,10 +27,18 @@ extension Version: ExpressibleByStringLiteral { } } + /// Initializes and returns a newly allocated version struct for the provided extended grapheme cluster. + /// + /// - Parameters: + /// - version: An extended grapheme cluster to use for creating a new version object. public init(extendedGraphemeClusterLiteral value: String) { self.init(stringLiteral: value) } + /// Initializes and returns a newly allocated version struct for the provided Unicode string. + /// + /// - Parameters: + /// - version: A Unicode string to use for creating a new version object. public init(unicodeScalarLiteral value: String) { self.init(stringLiteral: value) } @@ -34,6 +46,10 @@ extension Version: ExpressibleByStringLiteral { extension Version { + /// Initializes and returns a newly allocated version struct for the provided version. + /// + /// - Parameters: + /// - version: A version object to use for creating a new version object. public init(_ version: Version) { major = version.major minor = version.minor @@ -42,6 +58,10 @@ extension Version { buildMetadataIdentifiers = version.buildMetadataIdentifiers } + /// Initializes and returns a newly allocated version struct for the provided version string. + /// + /// - Parameters: + /// - version: A version string to use for creating a new version object. public init?(_ versionString: String) { let prereleaseStartIndex = versionString.index(of: "-") let metadataStartIndex = versionString.index(of: "+") diff --git a/Sources/PackageDescription4/Version.swift b/Sources/PackageDescription4/Version.swift index 293bb8a68c4..e93e84b30f7 100644 --- a/Sources/PackageDescription4/Version.swift +++ b/Sources/PackageDescription4/Version.swift @@ -8,52 +8,63 @@ See http://swift.org/CONTRIBUTORS.txt for Swift project authors */ -/// A struct representing a Semantic Version. +/// A semantic version. /// -/// Semantic versioning is a specification that proposes a set of rules and +/// A package's version must conform to the semantic versioning standard in order to ensure +/// that your package behaves in a predictable manner once developers update their +/// package dependency to a newer version. To achieve predictability, the semantic versioning specification proposes a set of rules and /// requirements that dictate how version numbers are assigned and incremented. -/// To learn more about the semantic versioning specification, visit -/// www.semver.org. /// -/// # Semantic Versioning (SemVer) 2.0.0 +/// A package version is a three period-separated integer. An example is `1.0.0`. /// -/// ## The Major Version -/// -/// The major version signifies breaking changes to the API which requires -/// updating existing clients. For example, renaming an existing type, removing -/// a method or changing a method’s signature are considered breaking changes. -/// This also includes any backwards incompatible bugfixes or behaviour changes -/// of existing API. +/// **The Major Version** /// -/// ## The Minor Version +/// The first digit of a version, or *major version*, signifies breaking changes to the API that require +/// updates to existing clients. For example, the semantic versioning specification +/// considers renaming an existing type, removing a method, or changing a method's signature +/// breaking changes. This also includes any backward-incompatible bug fixes or +/// behavioral changes of the existing API. /// -/// Update the minor version if functionality is added in a backward compatible -/// manner. For example, adding a new method or type without changing any other -/// API is considered backward-compatible. +/// **The Minor Version** +// +/// Update the second digit of a version, or *minor version*, if you add functionality in a backward-compatible manner. +/// For example, the semantic versioning specification considers adding a new method +/// or type without changing any other API to be backward-compatible. /// /// ## The Patch Version /// -/// Increase the patch version if you are making a backward-compatible bugfix. -/// This allows clients to benefit from bugfixes to your package without -/// incurring any maintenance burden. +/// Increase the third digit of a version, or *patch version* if you are making a backward-compatible bug fix. +/// This allows clients to benefit from bugfixes to your package without incurring +/// any maintenance burden. +/// +/// To learn more about the semantic versioning specification, visit +/// [semver.org](www.semver.org). public struct Version { - /// The major version. + /// The major version according to the semantic versioning standard. public let major: Int - /// The minor version. + /// The minor version according to the semantic versioning standard. public let minor: Int - /// The patch version. + /// The patch version according to the semantic versioning standard. public let patch: Int - /// The pre-release identifier. + /// The pre-release identifier according to the semantic versioning standard, such as `-beta.1`. public let prereleaseIdentifiers: [String] - /// The build metadata. + /// The build metadata of this version according to the semantic versioning standard, such as a commit hash. public let buildMetadataIdentifiers: [String] - /// Create a version object. + /// Initializes and returns a newly allocated version struct + /// for the provided components of a semantic version. + /// + /// - Parameters: + /// - major: The major version numner. + /// - minor: The minor version number. + /// - patch: The patch version number. + /// - prereleaseIdentifiers: The pre-release identifier. + /// - buildMetaDataIdentifiers: Build metadata that identifies a build. public init( _ major: Int, _ minor: Int, @@ -111,6 +122,7 @@ extension Version: Comparable { } extension Version: CustomStringConvertible { + /// A textual description of the version object. public var description: String { var base = "\(major).\(minor).\(patch)" if !prereleaseIdentifiers.isEmpty {