Minor Updates to the PackageDescription In-Source Documentation (swiftlang#2753)

* Address editorial feedback on in-source documentation.

* Use em-dashes in comments.

* Address some editorial feedback.

* A single-word change to the docs for an initializer.

Co-authored-by: Ben Scholtysik <[email protected]>

Author: Benjamin Scholtysik

Sources/PackageDescription/PackageDescription.swift

@@ -218,13 +218,14 @@ public final class Package {
     public var cxxLanguageStandard: CXXLanguageStandard?
 
   #if PACKAGE_DESCRIPTION_4
-    /// Initializes a Swift package with the provided configuration options.
+    /// Initializes a Swift package with configuration options you provide.
     ///
     /// - Parameters:
-    ///     - name: The name of the Swift package or `nil` to deduce the name from the package’s Git URL.
+    ///     - name: The name of the Swift package, or `nil`, if you want the Swift Package Manager to deduce the
+    ///           name from the package’s Git URL.
     ///     - pkgConfig: The name to use for C modules. If present, the Swift 
-    ///           Package Manager searches for a <name>.pc file to get the
-    ///           required additional flags for a system target.
+    ///           Package Manager searches for a `<name>.pc` file to get the
+    ///           additional flags required for a system target.
     ///     - providers: The package providers for a system package.
     ///     - products: The list of products that this package vends and that clients can use.
     ///     - dependencies: The list of package dependencies.
@@ -255,14 +256,15 @@ public final class Package {
         registerExitHandler()
     }
   #else
-    /// Initializes a Swift package with the provided configuration options.
+    /// Initializes a Swift package with configuration options you provide.
     ///
     /// - Parameters:
-    ///     - name: The name of the Swift package or `nil` to deduce the name from the package’s Git URL.
+    ///     - name: The name of the Swift package, or `nil`, if you want the Swift Package Manager to deduce the
+    ///           name from the package’s Git URL.
     ///     - pkgConfig: The name to use for C modules. If present, the Swift 
-    ///           Package Manager searches for a <name>.pc file to get the
-    ///           required additional flags for a system target.
-    ///     - products: The list of products that this package vends and that clients can use.
+    ///           Package Manager searches for a `<name>.pc` file to get the
+    ///           additional flags required for a system target.
+    ///     - products: The list of products that this package makes available for clients to use.
     ///     - 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.
@@ -292,15 +294,16 @@ public final class Package {
         registerExitHandler()
     }
 
-    /// Initializes a Swift package with the provided configuration options.
+    /// Initializes a Swift package with configuration options you provide.
     ///
     /// - Parameters:
-    ///     - name: The name of the Swift package or `nil` to deduce the name from the package’s Git URL.
-    ///     - platforms: The list of supported platforms with a custom deployment target.
+    ///     - name: The name of the Swift package, or `nil`, if you want the Swift Package Manager to deduce the
+    ///           name from the package’s Git URL.
+    ///     - platforms: The list of supported platforms that have a custom deployment target.
     ///     - pkgConfig: The name to use for C modules. If present, the Swift 
-    ///           Package Manager searches for a <name>.pc file to get the
-    ///           required additional flags for a system target.
-    ///     - products: The list of products that this package vends and that clients can use.
+    ///           Package Manager searches for a `<name>.pc` file to get the
+    ///           additional flags required for a system target.
+    ///     - products: The list of products that this package makes available for clients to use.
     ///     - 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.
@@ -332,15 +335,16 @@ public final class Package {
         registerExitHandler()
     }
 
-    /// Initializes a Swift package with the provided configuration options.
+    /// Initializes a Swift package with configuration options you provide.
     ///
     /// - Parameters:
-    ///     - name: The name of the Swift package or `nil` to deduce the name from the package’s Git URL.
+    ///     - name: The name of the Swift package, or `nil`, if you want the Swift Package Manager to deduce the
+    ///           name from the package’s Git URL.
     ///     - defaultLocalization: The default localization for resources.
-    ///     - platforms: The list of supported platforms with a custom deployment target.
+    ///     - platforms: The list of supported platforms that have a custom deployment target.
     ///     - pkgConfig: The name to use for C modules. If present, the Swift 
-    ///           Package Manager searches for a <name>.pc file to get the
-    ///           required additional flags for a system target.
+    ///           Package Manager searches for a `<name>.pc` file to get the
+    ///           additional flags required for a system target.
     ///     - products: The list of products that this package vends and that clients can use.
     ///     - dependencies: The list of package dependencies.
     ///     - targets: The list of targets that are part of this package.
@@ -410,8 +414,7 @@ public final class Package {
 
 /// A wrapper around an IETF language tag.
 ///
-/// To learn more about IETF language tags, a worldwide standard for language
-/// tags, visit [the IEFT website for RFC5646](https://tools.ietf.org/html/rfc5646).
+/// To learn more about the IETF worldwide standard for language tags, see [RFC5646](https://tools.ietf.org/html/rfc5646).
 public struct LanguageTag: Hashable {
 
     /// An IETF language tag.
@@ -464,7 +467,7 @@ public enum SystemPackageProvider {
   #endif
 
     /// Creates a system package provider with a list of installable packages
-    /// for users of the homebrew package manager on macOS.
+    /// for users of the HomeBrew package manager on macOS.
     ///
     /// - Parameters:
     ///     - packages: The list of package names.

Sources/PackageDescription/Resource.swift

@@ -11,20 +11,18 @@
 /// A resource to bundle with the Swift package.
 ///
 /// If a Swift package declares a Swift tools version of 5.3 or later, it can include resource files.
-/// Similar to source code, Xcode scopes resources to a target. As a result,
-/// you need to put them into the folder that corresponds to the target they belong to.
-/// For example, any resources for the `MyLibrary` target need to reside in `Sources/MyLibrary`.
-/// Use subdirectories to organize your resource files in a way that makes it easy to identify and manage them.
+/// Similar to source code, the Swift Package Manager scopes resources to a target, so you must put them
+/// into the folder that corresponds to the target they belong to.
+/// For example, any resources for the `MyLibrary` target must reside in `Sources/MyLibrary`.
+/// Use subdirectories to organize your resource files in a way that simplifies file identification and management.
 /// For example, put all resource files into a directory named `Resources`,
-/// so your resource files reside at `Sources/MyLibrary/Resources`.
-///
-/// Per default, Xcode handles common resources types for Apple platforms automatically.
-/// For example, you don’t need to declare XIB files, storyboards, CoreData file types, and asset catalogs
+/// so they reside at `Sources/MyLibrary/Resources.
+/// By default, the Swift Package Manager handles common resources types for Apple platforms automatically.
+/// For example, you don’t need to declare XIB files, storyboards, Core Data file types, and asset catalogs
 /// as resources in your package manifest.
-/// However, you must declare other file types, for example image files, as resources explicitly
-/// using the `process(_:localization:)` or `copy(_:)` rules.
-/// Alternatively, exclude resource files from a target by passing them to the
-/// target initializer’s `exclude` parameter. 
+/// However, you must explicitly declare other file types—for example image files—as resources
+/// using the `process(_:localization:)`` or `copy(_:)`` rules. Alternatively, exclude resource files from a target
+/// by passing them to the target initializer’s `exclude` parameter.
 public struct Resource: Encodable {
 
     /// Defines the explicit type of localization for resources.
@@ -54,7 +52,7 @@ public struct Resource: Encodable {
 
     /// Applies a platform-specific rule to the resource at the given path.
     ///
-    /// Use the process rule to process resources at the given path
+    /// Use the `process` rule to process resources at the given path
     /// according to the platform it builds the target for. For example, the
     /// Swift Package Manager may optimize image files for platforms that
     /// support such optimizations. If no optimization is available for a file
@@ -74,13 +72,12 @@ public struct Resource: Encodable {
 
     /// Applies the copy rule to a resource at the given path.
     ///
-    /// If possible, use `process(_:localization:)`` to automatically apply optimizations
+    /// If possible, use `process(_:localization:)`` and automatically apply optimizations
     /// to resources.
     ///
-    /// If you need resources to remain untouched or retain a specific folder structure,
-    /// use the copy rule. It copies resources at the given path as is to the top-level
-    /// in the package’s resource bundle.
-    /// If the given path represents a directory, the Swift Package Manager preserves its structure.
+    /// If your resources must remain untouched or must retain a specific folder structure,
+    /// use the `copy` rule. It copies resources at the given path, as is, to the top level
+    /// in the package’s resource bundle. If the given path represents a directory, Xcode preserves its structure.
     ///
     /// - Parameters:
     ///     - path: The path for a resource.