88 See http://swift.org/CONTRIBUTORS.txt for Swift project authors
99*/
1010
11- /// Defines a package product.
11+ /// The object that defines a package product.
1212///
13- /// A package product defines an externally visible build artifact that is
13+ /// A package product defines an externally visible build artifact that's
1414/// available to clients of a package. The product is assembled from the build
1515/// artifacts of one or more of the package's targets.
1616///
1717/// A package product can be one of two types:
1818///
19- /// 1. Library
19+ /// Library
2020///
21- /// A library product is used to vend library targets containing the public
22- /// APIs that will be available to clients .
21+ /// Use a library product to vend library targets. This makes a target's public APIs
22+ /// available to clients that integrate the Swift package .
2323///
24- /// 2. Executable
24+ /// Executable
2525///
26- /// An executable product is used to vend an executable target. This should
27- /// only be used if the executable needs to be made available to clients.
26+ /// Use an executable product to vend an executable target.
27+ /// Use this only if you want to make the executable available to clients.
2828///
2929/// The following example shows a package manifest for a library called "Paper"
3030/// that defines multiple products:
@@ -63,14 +63,14 @@ public class Product: Encodable {
6363 case type = " product_type "
6464 }
6565
66- /// The name of the product.
66+ /// The name of the package product.
6767 public let name : String
6868
6969 init ( name: String ) {
7070 self . name = name
7171 }
7272
73- /// Represents an executable product.
73+ /// The executable product of a Swift package .
7474 public final class Executable : Product {
7575 private enum ExecutableCodingKeys : CodingKey {
7676 case targets
@@ -84,6 +84,12 @@ public class Product: Encodable {
8484 super. init ( name: name)
8585 }
8686
87+ /// Encodes this executable product into the given encoder.
88+ ///
89+ /// This function throws an error if any values are invalid for the given encoder’s format.
90+ ///
91+ /// - Parameters:
92+ /// - encoder: The encoder to write data to.
8793 public override func encode( to encoder: Encoder ) throws {
8894 try . encode ( to: encoder)
8995 var productContainer = encoder. container ( keyedBy: ProductCodingKeys . self)
@@ -93,14 +99,14 @@ public class Product: Encodable {
9399 }
94100 }
95101
96- /// Represents a library product.
102+ /// The library product of a Swift package .
97103 public final class Library : Product {
98104 private enum LibraryCodingKeys : CodingKey {
99105 case type
100106 case targets
101107 }
102108
103- /// The type of library product.
109+ /// The different types of a library product.
104110 public enum LibraryType : String , Encodable {
105111 case `static`
106112 case `dynamic`
@@ -111,7 +117,8 @@ public class Product: Encodable {
111117
112118 /// The type of the library.
113119 ///
114- /// If the type is unspecified, package manager will automatically choose a type.
120+ /// If the type is unspecified, the Swift Package Manager automatically
121+ /// chooses a type based on the client’s preference.
115122 public let type : LibraryType ?
116123
117124 init ( name: String , type: LibraryType ? = nil , targets: [ String ] ) {
@@ -120,6 +127,12 @@ public class Product: Encodable {
120127 super. init ( name: name)
121128 }
122129
130+ /// Encodes this library product into the given encoder.
131+ ///
132+ /// This function throws an error if any values are invalid for the given encoder’s format.
133+ ///
134+ /// - Parameters:
135+ /// - encoder: The encoder to write data to.
123136 public override func encode( to encoder: Encoder ) throws {
124137 try . encode ( to: encoder)
125138 var productContainer = encoder. container ( keyedBy: ProductCodingKeys . self)
@@ -130,12 +143,13 @@ public class Product: Encodable {
130143 }
131144 }
132145
133- /// Create a library product that can be used by clients that depend on this package.
146+ /// Create a library product to allow clients that declare a dependency on this package
147+ /// to use the package’s functionality.
134148 ///
135- /// A library' s product can either be statically or dynamically linked. It
136- /// is recommended to not declare the type of library explicitly to let the
137- /// Swift Package Manager choose between static or dynamic linking depending
138- /// on the consumer of the package.
149+ /// A library’ s product can either be statically or dynamically linked.
150+ /// If possible, don’t declare the type of library explicitly to let
151+ /// the Swift Package Manager choose between static or dynamic linking based
152+ /// on the preference of the package's consumer .
139153 ///
140154 /// - Parameters:
141155 /// - name: The name of the library product.
@@ -151,18 +165,24 @@ public class Product: Encodable {
151165 return Library ( name: name, type: type, targets: targets)
152166 }
153167
154- /// Create an executable product.
168+ /// Create an executable package product that clients can run .
155169 ///
156170 /// - Parameters:
157171 /// - name: The name of the executable product.
158- /// - targets: The targets that are bundled into an executable product.
172+ /// - targets: The targets to bundle into an executable product.
159173 public static func executable(
160174 name: String ,
161175 targets: [ String ]
162176 ) -> Product {
163177 return Executable ( name: name, targets: targets)
164178 }
165179
180+ /// Encodes this product into the given encoder.
181+ ///
182+ /// This function throws an error if any values are invalid for the given encoder’s format.
183+ ///
184+ /// - Parameters:
185+ /// - encoder: The encoder to write data to.
166186 public func encode( to encoder: Encoder ) throws {
167187 var container = encoder. container ( keyedBy: ProductCodingKeys . self)
168188 try . encode ( name, forKey: . name)
0 commit comments