Improve the in-source docs of the PackageDescription API for better readability.

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
 

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(

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.

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]