Update in-source documentation (#2733)

* Update source docs for Resource and Target

* Another pass at the SwiftPM in-source documentation.

* A few more tweaks to in-source docs for SwiftPM.

* Use title case when refering to SwiftPM

* Address feedback on source docs.

* Correct in-source comment.

* Some more edits to the in-source documentation.

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

Author: Benjamin Scholtysik

Sources/PackageDescription/BuildSettings.swift

@@ -58,7 +58,7 @@ public struct BuildSettingCondition: Encodable {
         self.config = config
     }
 
-    /// Create a build setting condition.
+    /// Creates a build setting condition.
     ///
     /// At least one parameter is mandatory.
     ///
@@ -96,7 +96,7 @@ public struct CSetting: Encodable {
         self.data = BuildSettingData(name: name, value: value, condition: condition)
     }
 
-    /// Provide a header search path relative to the target's directory.
+    /// Provides a header search path relative to the target's directory.
     ///
     /// Use this setting to add a search path for headers within your target.
     /// You can't use absolute paths and you can't use this setting to provide
@@ -131,16 +131,16 @@ public struct CSetting: Encodable {
         return CSetting(name: "define", value: [settingValue], condition: condition)
     }
 
-    /// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
+    /// Sets 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 have any negative
     /// side effect on the build since certain flags can change the behavior of
-    /// how a build is performed.
+    /// how it performs a build.
     ///
     /// 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.
+    /// target ineligible for use by other packages.
     ///
     /// - Since: First available in PackageDescription 5.0
     ///
@@ -160,7 +160,7 @@ public struct CXXSetting: Encodable {
         self.data = BuildSettingData(name: name, value: value, condition: condition)
     }
 
-    /// Provide a header search path relative to the target's directory.
+    /// Provides a header search path relative to the target's directory.
     ///
     /// Use this setting to add a search path for headers within your target.
     /// You can't use absolute paths and you can't use this setting to provide
@@ -195,7 +195,7 @@ public struct CXXSetting: Encodable {
         return CXXSetting(name: "define", value: [settingValue], condition: condition)
     }
 
-    /// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
+    /// Sets 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 have any negative
@@ -223,7 +223,7 @@ public struct SwiftSetting: Encodable {
         self.data = BuildSettingData(name: name, value: value, condition: condition)
     }
 
-    /// Define a compilation condition.
+    /// Defines a compilation condition.
     ///
     /// Use compilation conditions to only compile statements if a certain condition is true.
     /// For example, the Swift compiler will only compile the
@@ -245,7 +245,7 @@ public struct SwiftSetting: Encodable {
         return SwiftSetting(name: "define", value: [name], condition: condition)
     }
 
-    /// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
+    /// Sets 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 have any negative
@@ -273,7 +273,7 @@ public struct LinkerSetting: Encodable {
         self.data = BuildSettingData(name: name, value: value, condition: condition)
     }
 
-    /// Declare linkage to a system library.
+    /// Declares linkage to a system library.
     ///
     /// This setting is most useful when the library can't be linked
     /// automatically, such as C++ based libraries and non-modular
@@ -288,7 +288,7 @@ public struct LinkerSetting: Encodable {
         return LinkerSetting(name: "linkedLibrary", value: [library], condition: condition)
     }
 
-    /// Declare linkage to a system framework.
+    /// Declares linkage to a system framework.
     ///
     /// This setting is most useful when the framework can't be linked
     /// automatically, such as C++ based frameworks and non-modular
@@ -303,7 +303,7 @@ public struct LinkerSetting: Encodable {
         return LinkerSetting(name: "linkedFramework", value: [framework], condition: condition)
     }
 
-    /// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
+    /// Sets 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 have any negative

Sources/PackageDescription/PackageDependency.swift

@@ -10,7 +10,7 @@
 
 extension Package.Dependency {
 
-    /// Create a package dependency that uses the version requirement, starting with the given minimum version,
+    /// Adds a package dependency that uses the version requirement, starting with the given minimum version,
     /// going up to the next major version.
     ///
     /// This is the recommended way to specify a remote package dependency.
@@ -20,7 +20,7 @@ extension Package.Dependency {
     /// while making sure you don't update to a version with breaking changes,
     /// and helps to prevent conflicts in your dependency graph.
     ///
-    /// The following example allows the Swift package manager to select a version
+    /// 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"),
@@ -37,7 +37,7 @@ extension Package.Dependency {
         return .init(name: nil, url: url, requirement: .upToNextMajor(from: version))
     }
 
-    /// Create a package dependency that uses the version requirement, starting with the given minimum version,
+    /// Adds a package dependency that uses the version requirement, starting with the given minimum version,
     /// going up to the next major version.
     ///
     /// This is the recommended way to specify a remote package dependency.
@@ -47,7 +47,7 @@ extension Package.Dependency {
     /// while making sure you don't update to a version with breaking changes,
     /// and helps to prevent conflicts in your dependency graph.
     ///
-    /// The following example allows the Swift package manager to select a version
+    /// 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"),
@@ -65,7 +65,7 @@ extension Package.Dependency {
         return .init(name: name, url: url, requirement: .upToNextMajor(from: version))
     }
 
-    /// Add a remote package dependency given a version requirement.
+    /// Adds a remote package dependency given a version requirement.
     ///
     /// - Parameters:
     ///     - name: The name of the package, or nil to deduce it from the URL.
@@ -80,10 +80,10 @@ extension Package.Dependency {
         return .init(name: nil, url: url, requirement: requirement)
     }
 
-    /// Add a remote package dependency given a version requirement.
+    /// Adds a remote package dependency with a given version requirement.
     ///
     /// - Parameters:
-    ///     - name: The name of the package, or nil to deduce it from the URL.
+    ///     - name: The name of the package, or `nil` to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - requirement: A dependency requirement. See static methods on `Package.Dependency.Requirement` for available options.
     @available(_PackageDescription, introduced: 5.2)
@@ -96,10 +96,10 @@ extension Package.Dependency {
         return .init(name: name, url: url, requirement: requirement)
     }
 
-    /// Add a package dependency starting with a specific minimum version, up to
+    /// Adds a package dependency starting with a specific minimum version, up to
     /// but not including a specified maximum version.
     ///
-    /// The following example allows the Swift package manager to pick
+    /// 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"),
@@ -120,16 +120,16 @@ extension Package.Dependency {
       #endif
     }
 
-    /// Add a package dependency starting with a specific minimum version, up to
+    /// Adds a package dependency starting with a specific minimum version, up to
     /// but not including a specified maximum version.
     ///
-    /// The following example allows the Swift package manager to pick
+    /// 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"),
     ///
     /// - Parameters:
-    ///     - name: The name of the package, or nil to deduce it from the URL.
+    ///     - name: The name of the package, or `nil` to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - range: The custom version range requirement.
     @available(_PackageDescription, introduced: 5.2)
@@ -145,16 +145,16 @@ extension Package.Dependency {
       #endif
     }
 
-    /// Add a package dependency starting with a specific minimum version, going
+    /// Adds a package dependency starting with a specific minimum version, going
     /// up to and including a specific maximum version.
     ///
-    /// The following example allows the Swift package manager to pick
+    /// 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"),
     ///
     /// - Parameters:
-    ///     - name: The name of the package, or nil to deduce it from the URL.
+    ///     - name: The name of the package, or `nil` to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - range: The closed version range requirement.
     @available(_PackageDescription, obsoleted: 5.2)
@@ -175,16 +175,16 @@ extension Package.Dependency {
       #endif
     }
 
-    /// Add a package dependency starting with a specific minimum version, going
+    /// Adds a package dependency starting with a specific minimum version, going
     /// up to and including a specific maximum version.
     ///
-    /// The following example allows the Swift package manager to pick
+    /// 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"),
     ///
     /// - Parameters:
-    ///     - name: The name of the package, or nil to deduce it from the URL.
+    ///     - name: The name of the package, or `nil` to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - range: The closed version range requirement.
     @available(_PackageDescription, introduced: 5.2)
@@ -207,7 +207,7 @@ extension Package.Dependency {
     }
 
   #if !PACKAGE_DESCRIPTION_4
-    /// Add a dependency to a local package on the filesystem.
+    /// Adds a package dependency to a local package on the filesystem.
     ///
     /// The Swift Package Manager uses the package dependency as-is
     /// and does not perform any source control access. Local package dependencies
@@ -222,14 +222,16 @@ extension Package.Dependency {
         return .init(name: nil, url: path, requirement: ._localPackageItem)
     }
 
-    /// Add a dependency to a local package on the filesystem.
+    /// Adds a package dependency to a local package on the filesystem.
     ///
     /// The Swift Package Manager uses the package dependency as-is
-    /// and does not perform any source control access. Local package dependencies
+    /// and doesn't 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.
+    /// - Parameters
+    ///   - name: The name of the Swift package or `nil` to deduce the name from path.
+    ///   - path: The local path to the package.
     @available(_PackageDescription, introduced: 5.2)
     public static func package(
         name: String? = nil,