[5.9] Documentation update. (swiftlang#6434)

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

Author: zkiraly

Sources/PackageDescription/BuildSettings.swift

@@ -12,6 +12,7 @@
 
 /// The build configuration such as debug or release.
 public struct BuildConfiguration {
+    /// The configuration of the build. Valid values are `debug` and `release`.
     let config: String
 
     private init(_ config: String) {
@@ -54,7 +55,9 @@ public struct BuildConfiguration {
 /// ),
 /// ```
 public struct BuildSettingCondition {
+    /// The applicable platforms for this build setting condition.
     let platforms: [Platform]?
+    /// The applicable build configuration for this build setting condition.
     let config: BuildConfiguration?
 
     private init(platforms: [Platform]?, config: BuildConfiguration?) {
@@ -113,6 +116,7 @@ struct BuildSettingData {
 
 /// A C-language build setting.
 public struct CSetting {
+    /// The abstract build setting data.
     let data: BuildSettingData
 
     private init(name: String, value: [String], condition: BuildSettingCondition?) {
@@ -182,6 +186,7 @@ public struct CSetting {
 
 /// A CXX-language build setting.
 public struct CXXSetting {
+    /// The abstract build setting data.
     let data: BuildSettingData
 
     private init(name: String, value: [String], condition: BuildSettingCondition?) {
@@ -250,6 +255,7 @@ public struct CXXSetting {
 
 /// A Swift language build setting.
 public struct SwiftSetting {
+    /// The abstract build setting data.
     let data: BuildSettingData
 
     private init(name: String, value: [String], condition: BuildSettingCondition?) {
@@ -306,13 +312,13 @@ public struct SwiftSetting {
 
     /// Enable an upcoming feature with the given name.
     ///
-    /// An upcoming feature is one that has been accepted into Swift as of a
+    /// An upcoming feature is one that is available in Swift as of a
     /// certain language version, but is not available by default in prior
     /// language modes because it has some impact on source compatibility.
     ///
-    /// Multiple upcoming features can be added to a given target, and can
-    /// be used in a target without affecting its dependencies. An unknown
-    /// upcoming feature will be ignored by the implementation.
+    /// You can add multiple upcoming features to a given target, and can
+    /// use in a target without affecting its dependencies. Targets will ignore any unknown
+    /// upcoming features.
     ///
     /// - Since: First available in PackageDescription 5.8.
     ///
@@ -332,11 +338,11 @@ public struct SwiftSetting {
     /// Enable an experimental feature with the given name.
     ///
     /// An experimental feature is one that is in development, but
-    /// has not been accepted into Swift as a language feature.
+    /// is not yet available in Swift as a language feature.
     ///
-    /// Multiple experimental features can be added to a given target, and can
-    /// be used in a target without affecting its dependencies. An unknown
-    /// experimental feature will be ignored by the implementation.
+    /// You can add multiple experimental features to a given target, and can
+    /// use in a target without affecting its dependencies. Targets will ignore any  unknown
+    /// experimental features.
     ///
     /// - Since: First available in PackageDescription 5.8.
     ///
@@ -391,6 +397,7 @@ public struct SwiftSetting {
 
 /// A linker build setting.
 public struct LinkerSetting {
+    /// The abstract build setting data.
     let data: BuildSettingData
 
     private init(name: String, value: [String], condition: BuildSettingCondition?) {

Sources/PackageDescription/PackageDescription.swift

@@ -380,6 +380,7 @@ public enum SystemPackageProvider {
     /// Packages installable by the yum package manager.
     @available(_PackageDescription, introduced: 5.3)
     case yumItem([String])
+    /// Packages installable by the NuGet package manager.
     @available(_PackageDescription, introduced: 999.0)
     case nugetItem([String])
 
@@ -416,7 +417,7 @@ public enum SystemPackageProvider {
     }
 
     /// Creates a system package provider with a list of installable packages
-    /// for users of the nuget package manager on Linux or Windows.
+    /// for users of the NuGet package manager on Linux or Windows.
     ///
     /// - Parameter packages: The list of package names.
     ///

Sources/PackageDescription/Resource.swift

@@ -47,7 +47,7 @@ public struct Resource {
 
     /// The rule for the resource.
     let rule: String
-
+	
     /// The path of the resource.
     let path: String
 
@@ -97,6 +97,10 @@ public struct Resource {
     }
 
     /// Applies the embed rule to a resource at the given path.
+    ///
+    /// You can use the embed rule to embed the contents of the resource into the executable code.
+    /// - Parameter path: The path for a resource.
+    /// - Returns: A `Resource` instance.
     @available(_PackageDescription, introduced: 5.9)
     public static func embedInCode(_ path: String) -> Resource {
         return Resource(rule: "embedInCode", path: path, localization: nil)

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

Sources/PackageDescription/Target.swift

@@ -551,7 +551,7 @@ public final class Target {
     ///
     /// - Parameters:
     ///   - name: The name of the target.
-    ///   - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside (package by default).
+    ///   - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside. The default value is `package`.
     ///   - dependencies: The dependencies of the target. A dependency can be another target in the package or a product from a package dependency.
     ///   - path: The custom path for the target. By default, the Swift Package Manager requires a target's sources to reside at predefined search paths;
     ///       for example, `[PackageRoot]/Sources/[TargetName]`.
@@ -724,7 +724,7 @@ public final class Target {
     ///
     /// - Parameters:
     ///   - name: The name of the target.
-    ///   - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside (package by default).
+    ///   - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside. The default value is `package`.
     ///   - dependencies: The dependencies of the target. A dependency can be another target in the package or a product from a package dependency.
     ///   - path: The custom path for the target. By default, the Swift Package Manager requires a target's sources to reside at predefined search paths;
     ///       for example, `[PackageRoot]/Sources/[TargetName]`.
@@ -972,7 +972,7 @@ public final class Target {
     ///
     /// - Parameters:
     ///   - name: The name of the target.
-    ///   - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside (package by default).
+    ///   - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside. The default value is `package`.
     ///   - dependencies: The dependencies of the target. A dependency can be another target in the package or a product from a package dependency.
     ///   - path: The custom path for the target. By default, the Swift Package Manager requires a target's sources to reside at predefined search paths;
     ///       for example, `[PackageRoot]/Sources/[TargetName]`.
@@ -1210,7 +1210,7 @@ public final class Target {
     ///
     /// - Parameters:
     ///   - name: The name of the plugin target.
-    ///   - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside (package by default).
+    ///   - group: The group this target belongs to, where access to the target's group-specific APIs is not allowed from outside. The default value is `package`.
     ///   - capability: The type of capability the plugin target provides.
     ///   - dependencies: The plugin target's dependencies.
     ///   - path: The path of the plugin target, relative to the package root.
@@ -1406,7 +1406,7 @@ public struct TargetDependencyCondition {
 
 extension Target.PluginCapability {
 
-    /// Specifies that the plugin provides a build tool capability.
+    /// The plugin is a build tool.
     ///
     /// The plugin will be applied to each target that uses it and should create commands
     /// that will run before or during the build of the target.
@@ -1490,7 +1490,7 @@ public enum PluginPermission {
     case writeToPackageDirectory(reason: String)
 }
 
-/// The scope of a network permission. This can be none, local connections only or all connections.
+/// The scope of a network permission. This can be none, local connections only, or all connections.
 @available(_PackageDescription, introduced: 5.9)
 public enum PluginNetworkPermissionScope {
     /// Do not allow network access.
@@ -1504,7 +1504,7 @@ public enum PluginNetworkPermissionScope {
     /// Allow connections to any unix domain socket.
     case unixDomainSocket
 
-    /// Allow local and outgoing network connections,  limited to a range of allowed ports.
+    /// Allow local and outgoing network connections, limited to a range of allowed ports.
     public static func all(ports: Range<UInt8>) -> PluginNetworkPermissionScope {
         return .all(ports: Array(ports))
     }