[5.9] Cherry-pick documentation updates (#6511)

* [5.9] Documentation update. (#6434)

* Updated documentation for BuildSettings.
* Updated documentation for PackageDescription.

* [5.9] Editorial review changes of PackageDescription documentation. (#6471)

Author: zkiraly

Sources/PackageDescription/BuildSettings.swift

@@ -10,8 +10,9 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// The build configuration such as debug or release.
+/// 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?) {
@@ -111,8 +114,9 @@ struct BuildSettingData {
     let condition: BuildSettingCondition?
 }
 
-/// A C-language build setting.
+/// A C language build setting.
 public struct CSetting {
+    /// The abstract build setting data.
     let data: BuildSettingData
 
     private init(name: String, value: [String], condition: BuildSettingCondition?) {
@@ -131,7 +135,7 @@ public struct CSetting {
     ///
     /// - Parameters:
     ///   - 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.
+    ///   - condition: A condition that restricts the use of the build setting.
     @available(_PackageDescription, introduced: 5.0)
     public static func headerSearchPath(_ path: String, _ condition: BuildSettingCondition? = nil) -> CSetting {
         return CSetting(name: "headerSearchPath", value: [path], condition: condition)
@@ -146,7 +150,7 @@ public struct CSetting {
     /// - Parameters:
     ///   - name: The name of the macro.
     ///   - value: The value of the macro.
-    ///   - condition: A condition that restricts the application of the build
+    ///   - condition: A condition that restricts the use of the build
     /// setting.
     @available(_PackageDescription, introduced: 5.0)
     public static func define(_ name: String, to value: String? = nil, _ condition: BuildSettingCondition? = nil) -> CSetting {
@@ -182,6 +186,7 @@ public struct CSetting {
 
 /// A CXX-language build setting.
 public struct CXXSetting {
+    /// The data store for the CXX build setting.
     let data: BuildSettingData
 
     private init(name: String, value: [String], condition: BuildSettingCondition?) {
@@ -200,6 +205,7 @@ public struct CXXSetting {
     ///
     /// - Parameters:
     ///   - 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.
     @available(_PackageDescription, introduced: 5.0)
     public static func headerSearchPath(_ path: String, _ condition: BuildSettingCondition? = nil) -> CXXSetting {
@@ -250,6 +256,7 @@ public struct CXXSetting {
 
 /// A Swift language build setting.
 public struct SwiftSetting {
+    /// The data store for the Swift build setting.
     let data: BuildSettingData
 
     private init(name: String, value: [String], condition: BuildSettingCondition?) {
@@ -306,18 +313,18 @@ 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
-    /// certain language version, but is not available by default in prior
+    /// An upcoming feature is one that is available in Swift as of a
+    /// certain language version, but isn't 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 and use multiple upcoming features in a given target
+    /// without affecting its dependencies. Targets will ignore any unknown
+    /// upcoming features.
     ///
     /// - Since: First available in PackageDescription 5.8.
     ///
     /// - Parameters:
-    ///   - name: The name of the upcoming feature, e.g., ConciseMagicFile.
+    ///   - name: The name of the upcoming feature; for example, `ConciseMagicFile`.
     ///   - condition: A condition that restricts the application of the build
     /// setting.
     @available(_PackageDescription, introduced: 5.8)
@@ -331,17 +338,17 @@ 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.
+    /// An experimental feature is one that's in development, but
+    /// 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 and use multiple experimental features in a given target
+    /// without affecting its dependencies. Targets will ignore any  unknown
+    /// experimental features.
     ///
     /// - Since: First available in PackageDescription 5.8.
     ///
     /// - Parameters:
-    ///   - name: The name of the experimental feature, e.g., VariadicGenerics.
+    ///   - name: The name of the experimental feature; for example, `VariadicGenerics`.
     ///   - condition: A condition that restricts the application of the build
     /// setting.
     @available(_PackageDescription, introduced: 5.8)
@@ -360,18 +367,18 @@ public struct SwiftSetting {
 
     /// Enable Swift interoperability with a given language.
     ///
-    /// This is useful for enabling Swift/C++ interoperability for a given
+    /// This is useful for enabling interoperability with Swift and C++ for a given
     /// target.
     ///
     /// Enabling C++ interoperability mode might alter the way some existing
-    /// C/Objective-C APIs are imported.
+    /// C and Objective-C APIs are imported.
     ///
     /// - Since: First available in PackageDescription 5.9.
     ///
     /// - Parameters:
-    ///   - mode: The language mode, either C or Cxx.
-    ///   - version: If Cxx language mode is used, the version of Swift/C++
-    /// interoperability, otherwise `nil`.
+    ///   - mode: The language mode, either C or CXX.
+    ///   - version: When using the CXX language mode, pass the version of Swift and C++
+    /// interoperability; otherwise, `nil`.
     ///   - condition: A condition that restricts the application of the build
     /// setting.
     @available(_PackageDescription, introduced: 5.9)
@@ -391,6 +398,7 @@ public struct SwiftSetting {
 
 /// A linker build setting.
 public struct LinkerSetting {
+    /// The data store for the Linker setting.
     let data: BuildSettingData
 
     private init(name: String, value: [String], condition: BuildSettingCondition?) {

Sources/PackageDescription/PackageDependency.swift

@@ -17,15 +17,15 @@ extension Package {
     /// A package dependency consists of a Git URL to the source of the package,
     /// and a requirement for the version of the package.
     ///
-    /// Swift Package Manager performs a process called _dependency resolution_ to figure out
+    /// Swift Package Manager performs a process called _dependency resolution_ to determine
     /// 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 {
-        /// The kind of dependency.
+        /// The type of dependency.
         @available(_PackageDescription, introduced: 5.6)
         public enum Kind {
             /// A dependency located at the given path.
@@ -482,11 +482,11 @@ extension Package.Dependency {
     /// Adds a package dependency that uses the exact version requirement.
     ///
     /// Specifying exact version requirements are not recommended as
-    /// they can cause conflicts in your dependency graph when multiple other packages depend on a package.
+    /// they can cause conflicts in your dependency graph when other packages depend on this package.
     /// As Swift packages follow the semantic versioning convention,
     /// think about specifying a version range instead.
     ///
-    /// The following example instruct the Swift Package Manager to use version `1.2.3`.
+    /// The following example instructs the Swift Package Manager to use version `1.2.3`.
     ///
     /// ```swift
     /// .package(url: "https://example.com/example-package.git", exact: "1.2.3"),
@@ -587,10 +587,10 @@ extension Package.Dependency {
     ///
     /// 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,
+    /// Because Swift packages follow the semantic versioning convention,
     /// think about specifying a version range instead.
     ///
-    /// The following example instruct the Swift Package Manager to use version `1.2.3`.
+    /// The following example instructs the Swift Package Manager to use version `1.2.3`.
     ///
     /// ```swift
     /// .package(id: "scope.name", exact: "1.2.3"),

Sources/PackageDescription/PackageDescription.docc/Curation/Extensions/Product-Executable.md

@@ -2,6 +2,6 @@
 
 ## Topics
 
-### Describing an Executable Product
+### Describing an executable product
 
 - ``targets``

Sources/PackageDescription/PackageDescription.docc/Curation/Platform.md

@@ -17,7 +17,7 @@
 - ``wasi``
 - ``windows``
 
-### Type Methods
+### Type methods
 
 - ``custom(_:)``
 

Sources/PackageDescription/PackageDescription.docc/Curation/Plugin.md

@@ -2,6 +2,6 @@
 
 ## Topics
 
-### Describing a Plugin Product
+### Describing a plug-in product
 
 - ``targets``

Sources/PackageDescription/PackageDescription.docc/Curation/PluginPermission.md

@@ -2,7 +2,7 @@
 
 ## Topics
 
-### Create a Permission
+### Create a permission
 
 - ``allowNetworkConnections(scope:reason:)``
 - ``writeToPackageDirectory(reason:)``

Sources/PackageDescription/PackageDescription.docc/Curation/Product.md

@@ -17,6 +17,6 @@
 - ``Product/plugin(name:targets:)``
 - ``Plugin``
 
-### Naming the Product
+### Naming the product
 
 - ``name``

Sources/PackageDescription/PackageDescription.docc/Curation/SupportedPlatforms.md

@@ -48,7 +48,7 @@
 
 - <doc:/documentation/PackageDescription/Platform/linux>
 
-### Type Methods
+### Type methods
 
 - ``custom(_:versionString:)``
 

Sources/PackageDescription/PackageDescription.docc/Curation/Target-Dependency.md

@@ -18,7 +18,7 @@
 - ``init(extendedGraphemeClusterLiteral:)``
 - ``init(unicodeScalarLiteral:)``
 
-### Identifying Related Types
+### Identifying related types
 
 - ``ExtendedGraphemeClusterLiteralType``
 - ``StringLiteralType``

Sources/PackageDescription/PackageDescription.swift

@@ -315,10 +315,10 @@ public final class Package {
 /// [RFC5646](https://tools.ietf.org/html/rfc5646).
 public struct LanguageTag: Hashable {
 
-    /// An IETF language tag.
+    /// An IETF BCP 47 standard language tag.
     let tag: String
 
-    /// Creates a language tag from its IETF string representation.
+    /// Creates a language tag from its [IETF BCP 47](https://datatracker.ietf.org/doc/html/rfc5646) string representation.
     ///
     /// - Parameter tag: The string representation of an IETF language tag.
     private init(_ tag: String) {
@@ -377,14 +377,15 @@ public enum SystemPackageProvider {
     case brewItem([String])
     /// Packages installable by the apt-get package manager.
     case aptItem([String])
-    /// Packages installable by the yum package manager.
+    /// Packages installable by the Yellowdog Updated, Modified (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])
 
     /// Creates a system package provider with a list of installable packages
-    /// for users of the HomeBrew package manager on macOS.
+    /// for people who use the HomeBrew package manager on macOS.
     ///
     /// - Parameter packages: The list of package names.
     ///
@@ -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.
     ///
@@ -451,7 +452,7 @@ private func dumpPackageAtExit(_ package: Package, to handle: Int) {
         guard let dumpInfo = dumpInfo else { return }
 
         let hFile: HANDLE = HANDLE(bitPattern: dumpInfo.handle)!
-        // NOTE: `_open_osfhandle` transfers ownership of the HANDLE to the file
+        // NOTE: `_open_osfhandle` transfers ownership of the `HANDLE` to the file
         // descriptor.  DO NOT invoke `CloseHandle` on `hFile`.
         let fd: CInt = _open_osfhandle(Int(bitPattern: hFile), _O_APPEND)
         // NOTE: `_fdopen` transfers ownership of the file descriptor to the

Sources/PackageDescription/PackageDescriptionSerializationConversion.swift

@@ -1,9 +1,9 @@
 //===----------------------------------------------------------------------===//
 //
-// This source file is part of the Swift open source project
+// This source file is part of the Swift open source project.
 //
-// Copyright (c) 2023 Apple Inc. and the Swift project authors
-// Licensed under Apache License v2.0 with Runtime Library Exception
+// Copyright (c) 2023 Apple Inc. and the Swift project authors.
+// Licensed under Apache License v2.0 with Runtime Library Exception.
 //
 // See http://swift.org/LICENSE.txt for license information
 // See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors

Sources/PackageDescription/Product.swift

@@ -105,9 +105,9 @@ public class Product {
         }
     }
 
-    /// The plugin product of a Swift package.
+    /// The plug-in product of a Swift package.
     public final class Plugin: Product {
-        /// The name of the plugin target to vend as a product.
+        /// The name of the plug-in target to vend as a product.
         public let targets: [String]
 
         init(name: String, targets: [String]) {

Sources/PackageDescription/Resource.swift

@@ -38,7 +38,7 @@ public struct Resource {
     /// Defines the explicit type of localization for resources.
     public enum Localization: String {
 
-        /// A constant that represents default internationalization.
+        /// A constant that represents default localization.
         case `default`
 
         /// A constant that represents base internationalization.
@@ -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)

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) {