Part 1 of the PackageDescription DocC documentation update (#4276)

* Part 1 of the documentation update.

* Corrected the docs for two `Package.Dependency` methods.

* Changed the docs for the C language standards in response to PR comments.

* Updated all the language standard identifier docs.

* More responses to comments on the PR.

* Responded to more comments.

* Some light editing of the DocC documentation.

* More small edits.

* More minor edits.

* Fixed a typo.

* Removed unwanted blank-space.

* Responding to Anders' notes.

* I should not have touched this file, so I am reverting my changes there.

* We can't link below the top level for legal reasons.

* A small editorial change.

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

Author: zkiraly

Sources/PackageDescription/BuildSettings.swift

@@ -81,17 +81,15 @@ public struct BuildSettingCondition: Encodable {
 
     /// Creates a build setting condition.
     ///
-    /// - Parameters:
-    ///   - platforms: The applicable platforms for this build setting condition.
+    /// - Parameter platforms: The applicable platforms for this build setting condition.
     @available(_PackageDescription, introduced: 5.7)
     public static func when(platforms: [Platform]) -> BuildSettingCondition {
         BuildSettingCondition(platforms: platforms, config: .none)
     }
 
     /// Creates a build setting condition.
     ///
-    /// - Parameters:
-    ///   - configuration: The applicable build configuration for this build setting condition.
+    /// - Parameter configuration: The applicable build configuration for this build setting condition.
     @available(_PackageDescription, introduced: 5.7)
     public static func when(configuration: BuildConfiguration) -> BuildSettingCondition {
         BuildSettingCondition(platforms: .none, config: configuration)

Sources/PackageDescription/Context.swift

@@ -10,13 +10,15 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// The context a Swift package is running in. This encapsulates states that are known at build-time.
-/// For example where in the file system the current package resides.
+/// The context information for a Swift package.
+///
+/// The context encapsulates states that are known when Swift Package Manager interprets the package manifest,
+/// for example the location in the file system where the current package resides.
 @available(_PackageDescription, introduced: 5.6)
 public struct Context {
     private static let model = try! ContextModel.decode()
 
-    /// The directory containing Package.swift.
+    /// The directory that contains `Package.swift`.
     public static var packageDirectory : String {
         model.packageDirectory
     }

Sources/PackageDescription/LanguageStandardSettings.swift

@@ -10,161 +10,160 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// The supported C language standard to use for compiling C sources in the package.
-///
-/// Aliases are available for some C language standards. For example,
-/// use `c89`, `c90`, or `iso9899_1990` for the "ISO C 1990" standard.
-/// To learn more, read the [Clang Compiler User's Manual][1].
-///
-/// [1]: <https://clang.llvm.org/docs/UsersManual.html#differences-between-various-standard-modes>
+/// The supported C language standard you use to compile C sources in the
+/// package.
 public enum CLanguageStandard: String, Encodable {
 
-    /// ISO C 1990.
+    /// The identifier for the ISO C 1990 language standard.
     case c89
 
-    /// ISO C 1990.
+    /// The identifier for the ISO C 1990 language standard.
     case c90
 
-    /// ISO C 1999.
+    /// The identifier for the ISO C 1999 language standard.
     case c99
 
-    /// ISO C 2011.
+    /// The identifier for the ISO C 2011 language standard.
     case c11
 
-    /// ISO C 2017.
+    /// The identifier for the ISO C 2017 language stadard.
     @available(_PackageDescription, introduced: 5.4)
     case c17
 
-    /// ISO C 2017.
+    /// The identifier for the ISO C 2017 language standard.
     @available(_PackageDescription, introduced: 5.4)
     case c18
 
-    /// Working Draft for ISO C2x.
+    /// The identifier for the ISO C2x draft language standard.
     @available(_PackageDescription, introduced: 5.4)
     case c2x
 
-    /// ISO C 1990 with GNU extensions.
+    /// The identifier for the ISO C 1990 language standard with GNU extensions.
     case gnu89
 
-    /// ISO C 1990 with GNU extensions.
+    /// The identifier for the ISO C 1990 language standard with GNU extensions.
     case gnu90
 
-    /// ISO C 1999 with GNU extensions.
+    /// The identifier for the ISO C 1999 language standard with GNU extensions.
     case gnu99
 
-    /// ISO C 2011 with GNU extensions.
+    /// The identifier for the ISO C 2011 language standard with GNU extensions.
     case gnu11
 
-    /// ISO C 2017 with GNU extensions.
+    /// The identifier for the ISO C 2017 language standard with GNU extensions.
     @available(_PackageDescription, introduced: 5.4)
     case gnu17
 
-    /// ISO C 2017 with GNU extensions.
+    /// The identifier for the ISO C 2017 language standard with GNU extensions.
     @available(_PackageDescription, introduced: 5.4)
     case gnu18
 
-    /// Working Draft for ISO C2x with GNU extensions.
+    /// The identifier for the ISO C2x draft language standard with GNU extensions.
     @available(_PackageDescription, introduced: 5.4)
     case gnu2x
 
-    /// ISO C 1990.
+    /// The identifier for the ISO C 1990 language standard.
     case iso9899_1990 = "iso9899:1990"
 
-    /// ISO C 1990 with amendment 1.
+    /// The identifier for the ISO C 1990 language standard with amendment 1.
     case iso9899_199409 = "iso9899:199409"
 
-    /// ISO C 1999.
+    /// The identifier for the ISO C 1999 language standard.
     case iso9899_1999 = "iso9899:1999"
 
-    /// ISO C 2011.
+    /// The identifier for the ISO C 2011 language standard.
     case iso9899_2011 = "iso9899:2011"
 
-    /// ISO C 2017.
+    /// The identifier for the ISO C 2017 language standard.
     @available(_PackageDescription, introduced: 5.4)
     case iso9899_2017 = "iso9899:2017"
 
-    /// ISO C 2017.
+    /// The identifier for the ISO C 2017 language standard.
     @available(_PackageDescription, introduced: 5.4)
     case iso9899_2018 = "iso9899:2018"
 }
 
-/// The supported C++ language standard to use for compiling C++ sources in the package.
+/// The supported C++ language standard you use to compile C++ sources in the
+/// package.
 ///
 /// Aliases are available for some C++ language standards. For example,
 /// use `cxx98` or `cxx03` for the "ISO C++ 1998 with amendments" standard.
-/// To learn more, read the [C++ Support in Clang][1] status page.
-///
-/// [1]: <https://clang.llvm.org/cxx_status.html>
+/// To learn more, see [C++ Support in Clang](https://clang.llvm.org/cxx_status.html).
 public enum CXXLanguageStandard: String, Encodable {
 
-    /// ISO C++ 1998 with amendments.
+    /// The identifier for the ISO C++ 1998 language standard with amendments.
     case cxx98 = "c++98"
 
-    /// ISO C++ 1998 with amendments.
+    /// The identifier for the ISO C++ 1998 language standard with amendments.
     case cxx03 = "c++03"
 
-    /// ISO C++ 2011 with amendments.
+    /// The identifier for the ISO C++ 2011 language standard with amendments.
     case cxx11 = "c++11"
 
-    /// ISO C++ 2014 with amendments.
+    /// The identifier for the ISO C++ 2014 language standard with amendments.
     case cxx14 = "c++14"
 
-    /// ISO C++ 2017 with amendments.
+    /// The identifier for the ISO C++ 2017 language standard with amendments.
     @available(_PackageDescription, introduced: 5.4)
     case cxx17 = "c++17"
 
-    /// ISO C++ 2017 with amendments.
+    /// The identifier for the ISO C++ 2017 language standard with amendments.
     @available(_PackageDescription, introduced: 4, deprecated: 5.4, renamed: "cxx17")
     case cxx1z = "c++1z"
 
-    /// ISO C++ 2020 DIS.
+    /// The identifier for the ISO C++ 2020 language standard.
     @available(_PackageDescription, introduced: 5.4)
     case cxx20 = "c++20"
 
-    /// Working draft for ISO C++ 2023 DIS.
+    /// The identifier for the ISO C++ 2023 draft language standard.
     @available(_PackageDescription, introduced: 5.6)
     case cxx2b = "c++2b"
 
-    /// ISO C++ 1998 with amendments and GNU extensions.
+    /// The identifier for the ISO C++ 1998 language standard with amendments and GNU extensions.
     case gnucxx98 = "gnu++98"
 
-    /// ISO C++ 1998 with amendments and GNU extensions.
+    /// The identifier for the ISO C++ 1998 language standard with amendments and GNU extensions.
     case gnucxx03 = "gnu++03"
 
-    /// ISO C++ 2011 with amendments and GNU extensions.
+    /// The identifier for the ISO C++ 2011 language standard with amendments and GNU extensions.
     case gnucxx11 = "gnu++11"
 
-    /// ISO C++ 2014 with amendments and GNU extensions.
+    /// The identifier for the ISO C++ 2014 language standard with amendments and GNU extensions.
     case gnucxx14 = "gnu++14"
 
-    /// ISO C++ 2017 with amendments and GNU extensions.
+    /// The identifier for the ISO C++ 2017 language standard with amendments and GNU extensions.
     @available(_PackageDescription, introduced: 5.4)
     case gnucxx17 = "gnu++17"
 
-    /// ISO C++ 2017 with amendments and GNU extensions.
+    /// The identifier for the ISO C++ 2017 language standard with amendments and GNU extensions.
     @available(_PackageDescription, introduced: 4, deprecated: 5.4, renamed: "gnucxx17")
     case gnucxx1z = "gnu++1z"
 
-    /// ISO C++ 2020 DIS with GNU extensions.
+    /// The identifier for the ISO C++ 2020 language standard with GNU extensions.
     @available(_PackageDescription, introduced: 5.4)
     case gnucxx20 = "gnu++20"
 
-    /// Working draft for ISO C++ 2023 DIS with GNU extensions.
+    /// The identifier for the ISO C++ 2023 draft language standard with GNU extensions.
     @available(_PackageDescription, introduced: 5.6)
     case gnucxx2b = "gnu++2b"
 }
 
-/// The version of the Swift language to use for compiling Swift sources in the package.
+/// The version of the Swift language you use to compile Swift sources in the
+/// package.
 public enum SwiftVersion {
+    /// The identifier for the Swift 3 language version.
     @available(_PackageDescription, introduced: 4, obsoleted: 5)
     case v3
 
+    /// The identifier for the Swift 4 language version.
     @available(_PackageDescription, introduced: 4)
     case v4
 
+    /// The identifier for the Swift 4.2 language version.
     @available(_PackageDescription, introduced: 4)
     case v4_2
 
+    /// The identifier for the Swift 5 language version.
     @available(_PackageDescription, introduced: 5)
     case v5