Part 2 of the PackageDescription DocC documentation update (#4277)

* Part 2 of the documentation update.

* Adopted some of the comments from the companion PR #4276.

* A few minor edits to the DocC documentation comments.

* More minor edits.

* Another minor edit.

* Removed some unwanted blank-space.

* Changed "apply" to 3rd person present tense.

* Removed blank-space.

* Fixed a typo/

* Added back the Since docs that were deleted.

Co-authored-by: Zsolt Kiraly <[email protected]>

Author: zkiraly

Sources/PackageDescription/BuildSettings.swift

@@ -28,28 +28,31 @@ public struct BuildConfiguration: Encodable {
 /// A condition that limits the application of a build setting.
 ///
 /// By default, build settings are applicable for all platforms and build
-/// configurations. Use the ``when(platforms:configuration:)`` modifier to define  a build
-/// setting for a specific condition. Invalid usage of `.when` emits an error during
-/// manifest parsing. For example, it's invalid to specify a `.when` condition with
-/// both parameters as `nil`.
+/// configurations. Use the `.when` modifier to define a build setting for a
+/// specific condition. Invalid usage of `.when` emits an error during manifest
+/// parsing. For example, it's invalid to specify a `.when` condition with both
+/// parameters as `nil`.
 ///
-/// The following example shows how to use build setting conditions with various APIs:
+/// The following example shows how to use build setting conditions with various
+/// APIs:
 ///
-///     ...
-///     .target(
-///         name: "MyTool",
-///         dependencies: ["Utility"],
-///         cSettings: [
-///             .headerSearchPath("path/relative/to/my/target"),
-///             .define("DISABLE_SOMETHING", .when(platforms: [.iOS], configuration: .release)),
-///         ],
-///         swiftSettings: [
-///             .define("ENABLE_SOMETHING", .when(configuration: .release)),
-///         ],
-///         linkerSettings: [
-///             .linkedLibrary("openssl", .when(platforms: [.linux])),
-///         ]
-///     ),
+/// ```swift
+/// ...
+/// .target(
+///     name: "MyTool",
+///     dependencies: ["Utility"],
+///     cSettings: [
+///         .headerSearchPath("path/relative/to/my/target"),
+///         .define("DISABLE_SOMETHING", .when(platforms: [.iOS], configuration: .release)),
+///     ],
+///     swiftSettings: [
+///         .define("ENABLE_SOMETHING", .when(configuration: .release)),
+///     ],
+///     linkerSettings: [
+///         .linkLibrary("openssl", .when(platforms: [.linux])),
+///     ]
+/// ),
+/// ```
 public struct BuildSettingCondition: Encodable {
 
     private let platforms: [Platform]?
@@ -125,10 +128,10 @@ public struct CSetting: Encodable {
     ///
     /// The path must be a directory inside the package.
     ///
-    /// - Since: First available in PackageDescription 5.0
+    /// - Since: First available in PackageDescription 5.0.
     ///
     /// - Parameters:
-    ///   - path: The path of the directory that contains the  headers. The path is relative to the target's directory.
+    ///   - 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.
     public static func headerSearchPath(_ path: String, _ condition: BuildSettingCondition? = nil) -> CSetting {
         return CSetting(name: "headerSearchPath", value: [path], condition: condition)
@@ -138,12 +141,13 @@ public struct CSetting: Encodable {
     ///
     /// If you don't specify a value, the macro's default value is 1.
     ///
-    /// - Since: First available in PackageDescription 5.0
+    /// - Since: First available in PackageDescription 5.0.
     ///
     /// - Parameters:
     ///   - name: The name of the macro.
     ///   - value: The value of the macro.
-    ///   - condition: A condition that restricts the application of the build setting.
+    ///   - condition: A condition that restricts the application of the build
+    /// setting.
     public static func define(_ name: String, to value: String? = nil, _ condition: BuildSettingCondition? = nil) -> CSetting {
         var settingValue = name
         if let value = value {
@@ -152,22 +156,23 @@ public struct CSetting: Encodable {
         return CSetting(name: "define", value: [settingValue], condition: condition)
     }
 
-    /// Sets 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 it performs a build.
+    /// As the usage of the word “unsafe” implies, 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 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
+    /// behavior, the use of unsafe flags makes the products containing this
     /// target ineligible for use by other packages.
     ///
-    /// - Since: First available in PackageDescription 5.0
+    /// - Since: First available in PackageDescription 5.0.
     ///
     /// - Parameters:
     ///   - flags: The unsafe flags to set.
-    ///   - condition: A condition that restricts the application of the build setting.
+    ///   - condition: A condition that restricts the application of the build
+    /// setting.
     public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> CSetting {
         return CSetting(name: "unsafeFlags", value: flags, condition: condition)
     }
@@ -189,10 +194,10 @@ public struct CXXSetting: Encodable {
     ///
     /// The path must be a directory inside the package.
     ///
-    /// - Since: First available in PackageDescription 5.0
+    /// - Since: First available in PackageDescription 5.0.
     ///
     /// - Parameters:
-    ///   - path: The path of the directory that contains the  headers. The path is relative to the target's directory.
+    ///   - path: The path of the directory that contains the headers. The path is
     ///   - condition: A condition that restricts the application of the build setting.
     public static func headerSearchPath(_ path: String, _ condition: BuildSettingCondition? = nil) -> CXXSetting {
         return CXXSetting(name: "headerSearchPath", value: [path], condition: condition)
@@ -202,12 +207,13 @@ public struct CXXSetting: Encodable {
     ///
     /// If you don't specify a value, the macro's default value is 1.
     ///
-    /// - Since: First available in PackageDescription 5.0
+    /// - Since: First available in PackageDescription 5.0.
     ///
     /// - Parameters:
     ///   - name: The name of the macro.
     ///   - value: The value of the macro.
-    ///   - condition: A condition that restricts the application of the build setting.
+    ///   - condition: A condition that restricts the application of the build
+    /// setting.
     public static func define(_ name: String, to value: String? = nil, _ condition: BuildSettingCondition? = nil) -> CXXSetting {
         var settingValue = name
         if let value = value {
@@ -216,21 +222,22 @@ public struct CXXSetting: Encodable {
         return CXXSetting(name: "define", value: [settingValue], condition: condition)
     }
 
-    /// Sets 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.
+    /// As the usage of the word “unsafe” implies, 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 it performs a build.
     ///
     /// As some build flags can be exploited for unsupported or malicious
-    /// behavior, a product can't be used as a dependency in another package if one of its targets uses unsafe flags.
+    /// behavior, you can't use products with unsafe build flags as dependencies in another package.
     ///
-    /// - Since: First available in PackageDescription 5.0
+    /// - Since: First available in PackageDescription 5.0.
     ///
     /// - Parameters:
     ///   - flags: The unsafe flags to set.
-    ///   - condition: A condition that restricts the application of the build setting.
+    ///   - condition: A condition that restricts the application of the build
+    /// setting.
     public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> CXXSetting {
         return CXXSetting(name: "unsafeFlags", value: flags, condition: condition)
     }
@@ -246,41 +253,46 @@ public struct SwiftSetting: Encodable {
 
     /// 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
+    /// Use compilation conditions to only compile statements if a certain
+    /// condition is true. For example, the Swift compiler will only compile the
     /// statements inside the `#if` block when `ENABLE_SOMETHING` is defined:
     ///
-    ///     #if ENABLE_SOMETHING
-    ///        ...
-    ///     #endif
+    /// ```swift
+    /// #if ENABLE_SOMETHING
+    ///    ...
+    /// #endif
+    /// ```
     ///
-    /// Unlike macros in C/C++, compilation conditions don't have an
-    /// associated value.
+    /// Unlike macros in C/C++, compilation conditions don't have an associated
+    /// value.
     ///
-    /// - Since: First available in PackageDescription 5.0
+    /// - Since: First available in PackageDescription 5.0.
     ///
     /// - Parameters:
     ///   - name: The name of the macro.
-    ///   - condition: A condition that restricts the application of the build setting.
+    ///   - condition: A condition that restricts the application of the build
+    /// setting.
     public static func define(_ name: String, _ condition: BuildSettingCondition? = nil) -> SwiftSetting {
         return SwiftSetting(name: "define", value: [name], condition: condition)
     }
 
-    /// Sets unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
+    /// Set 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.
+    /// As the usage of the word “unsafe” implies, 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 it performs a build.
     ///
     /// As some build flags can be exploited for unsupported or malicious
-    /// behavior, a product can't be used as a dependency in another package if one of its targets uses unsafe flags.
+    /// behavior, the use of unsafe flags makes the products containing this
+    /// target ineligible for use by other packages.
     ///
-    /// - Since: First available in PackageDescription 5.0
+    /// - Since: First available in PackageDescription 5.0.
     ///
     /// - Parameters:
     ///   - flags: The unsafe flags to set.
-    ///   - condition: A condition that restricts the application of the build setting..
+    ///   - condition: A condition that restricts the application of the build
+    /// setting.
     public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> SwiftSetting {
         return SwiftSetting(name: "unsafeFlags", value: flags, condition: condition)
     }
@@ -297,48 +309,50 @@ public struct LinkerSetting: Encodable {
     /// 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
-    /// libraries.
+    /// automatically, such as C++ based libraries and non-modular libraries.
     ///
-    /// - Since: First available in PackageDescription 5.0
+    /// - Since: First available in PackageDescription 5.0.
     ///
     /// - Parameters:
     ///   - library: The library name.
-    ///   - condition: A condition that restricts the application of the build setting.
+    ///   - condition: A condition that restricts the application of the build
+    /// setting.
     public static func linkedLibrary(_ library: String, _ condition: BuildSettingCondition? = nil) -> LinkerSetting {
         return LinkerSetting(name: "linkedLibrary", value: [library], condition: condition)
     }
 
     /// 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
-    /// frameworks.
+    /// automatically, such as C++ based frameworks and non-modular frameworks.
     ///
-    /// - Since: First available in PackageDescription 5.0
+    /// - Since: First available in PackageDescription 5.0.
     ///
     /// - Parameters:
     ///   - framework: The framework name.
-    ///   - condition: A condition that restricts the application of the build setting.
+    ///   - condition: A condition that restricts the application of the build
+    /// setting.
     public static func linkedFramework(_ framework: String, _ condition: BuildSettingCondition? = nil) -> LinkerSetting {
         return LinkerSetting(name: "linkedFramework", value: [framework], condition: condition)
     }
-
-    /// Sets 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.
+    /// As the usage of the word “unsafe” implies, 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 it performs a build.
     ///
     /// As some build flags can be exploited for unsupported or malicious
-    /// behavior, a product can't be used as a dependency in another package if one of its targets uses unsafe flags.
+    /// behavior, the use of unsafe flags makes the products containing this
+    /// target ineligible for use by other packages.
     ///
-    /// - Since: First available in PackageDescription 5.0
+    /// - Since: First available in PackageDescription 5.0.
     ///
     /// - Parameters:
     ///   - flags: The unsafe flags to set.
-    ///   - condition: A condition that restricts the application of the build setting.
+    ///   - condition: A condition that restricts the application of the build
+    /// setting.
     public static func unsafeFlags(_ flags: [String], _ condition: BuildSettingCondition? = nil) -> LinkerSetting {
         return LinkerSetting(name: "unsafeFlags", value: flags, condition: condition)
     }

Sources/PackageDescription/PackageDescription.docc/Curation/BuildConfiguration.md

@@ -0,0 +1,12 @@
+# ``PackageDescription/BuildConfiguration``
+
+## Topics
+
+### Describing Build Configurations
+
+- ``debug``
+- ``release``
+
+### Encoding and Decoding
+
+- ``encode(to:)``

Sources/PackageDescription/PackageDescription.docc/Curation/BuildSettingCondition.md

@@ -0,0 +1,14 @@
+# ``PackageDescription/BuildSettingCondition``
+
+## Topics
+
+### Checking for a Build Condition
+
+- ``when(platforms:)``
+- ``when(configuration:)``
+- ``when(platforms:configuration:)-2991l``
+- ``when(platforms:configuration:)-475co``
+
+### Encoding and Decoding
+
+- ``encode(to:)``

Sources/PackageDescription/PackageDescription.docc/Curation/CSetting.md

@@ -0,0 +1,13 @@
+# ``PackageDescription/CSetting``
+
+## Topics
+
+### Configuring C Settings
+
+- ``define(_:to:_:)``
+- ``headerSearchPath(_:_:)``
+- ``unsafeFlags(_:_:)``
+
+### Encoding and Decoding
+
+- ``encode(to:)``

Sources/PackageDescription/PackageDescription.docc/Curation/CXXSetting.md

@@ -0,0 +1,13 @@
+# ``PackageDescription/CXXSetting``
+
+## Topics
+
+### Configuring CXX Settings
+
+- ``define(_:to:_:)``
+- ``headerSearchPath(_:_:)``
+- ``unsafeFlags(_:_:)``
+
+### Encoding and Decoding
+
+- ``encode(to:)``

Sources/PackageDescription/PackageDescription.docc/Curation/Extensions/Library-LibraryType-hash.md

@@ -0,0 +1,14 @@
+# ``PackageDescription/Product/Library/LibraryType/hash(into:)``
+
+@Metadata {
+   @DocumentationExtension(mergeBehavior: override)
+}
+
+Hashes the essential components of this value by feeding them into the given hasher.
+
+Implement this method to conform to the Hashable protocol. The components used for hashing must be the same as the components compared in your type’s == operator implementation. Call hasher.combine(_:) with each of these components.
+
+> Important:
+> Never call finalize() on hasher. Doing so may become a compile-time error in the future.
+
+- Parameter into: The hasher to use when combining the components of this instance.

Sources/PackageDescription/PackageDescription.docc/Curation/Extensions/Library-LibraryType-hashValue.md

@@ -0,0 +1,7 @@
+# ``PackageDescription/Product/Library/LibraryType/hashValue``
+
+@Metadata {
+   @DocumentationExtension(mergeBehavior: override)
+}
+
+The library type’s hash value.

Sources/PackageDescription/PackageDescription.docc/Curation/Extensions/Library-LibraryType-initRawValue.md

@@ -0,0 +1,11 @@
+# ``PackageDescription/Product/Library/LibraryType/init(rawValue:)``
+
+@Metadata {
+   @DocumentationExtension(mergeBehavior: override)
+}
+
+Creates a new instance with the specified raw value.
+
+- Parameter rawValue: The raw value to use for the new instance.
+
+If there is no value of the type that corresponds with the specified raw value, this initializer returns `nil`.