Skip to content

Commit 0d8e8d9

Browse files
Benjamin ScholtysikElektrojungeAtWork
Benjamin Scholtysik
andauthored
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]>
1 parent 8e4697d commit 0d8e8d9

9 files changed

+265
-211
lines changed

Sources/PackageDescription/BuildSettings.swift

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ public struct BuildSettingCondition: Encodable {
5858
self.config = config
5959
}
6060

61-
/// Create a build setting condition.
61+
/// Creates a build setting condition.
6262
///
6363
/// At least one parameter is mandatory.
6464
///
@@ -96,7 +96,7 @@ public struct CSetting: Encodable {
9696
self.data = BuildSettingData(name: name, value: value, condition: condition)
9797
}
9898

99-
/// Provide a header search path relative to the target's directory.
99+
/// Provides a header search path relative to the target's directory.
100100
///
101101
/// Use this setting to add a search path for headers within your target.
102102
/// You can't use absolute paths and you can't use this setting to provide
@@ -131,16 +131,16 @@ public struct CSetting: Encodable {
131131
return CSetting(name: "define", value: [settingValue], condition: condition)
132132
}
133133

134-
/// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
134+
/// Sets unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
135135
///
136136
/// As the usage of the word "unsafe" implies, the Swift Package Manager
137137
/// can't safely determine if the build flags have any negative
138138
/// side effect on the build since certain flags can change the behavior of
139-
/// how a build is performed.
139+
/// how it performs a build.
140140
///
141141
/// As some build flags can be exploited for unsupported or malicious
142142
/// behavior, the use of unsafe flags make the products containing this
143-
/// target ineligible to be used by other packages.
143+
/// target ineligible for use by other packages.
144144
///
145145
/// - Since: First available in PackageDescription 5.0
146146
///
@@ -160,7 +160,7 @@ public struct CXXSetting: Encodable {
160160
self.data = BuildSettingData(name: name, value: value, condition: condition)
161161
}
162162

163-
/// Provide a header search path relative to the target's directory.
163+
/// Provides a header search path relative to the target's directory.
164164
///
165165
/// Use this setting to add a search path for headers within your target.
166166
/// You can't use absolute paths and you can't use this setting to provide
@@ -195,7 +195,7 @@ public struct CXXSetting: Encodable {
195195
return CXXSetting(name: "define", value: [settingValue], condition: condition)
196196
}
197197

198-
/// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
198+
/// Sets unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
199199
///
200200
/// As the usage of the word "unsafe" implies, the Swift Package Manager
201201
/// can't safely determine if the build flags have any negative
@@ -223,7 +223,7 @@ public struct SwiftSetting: Encodable {
223223
self.data = BuildSettingData(name: name, value: value, condition: condition)
224224
}
225225

226-
/// Define a compilation condition.
226+
/// Defines a compilation condition.
227227
///
228228
/// Use compilation conditions to only compile statements if a certain condition is true.
229229
/// For example, the Swift compiler will only compile the
@@ -245,7 +245,7 @@ public struct SwiftSetting: Encodable {
245245
return SwiftSetting(name: "define", value: [name], condition: condition)
246246
}
247247

248-
/// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
248+
/// Sets unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
249249
///
250250
/// As the usage of the word "unsafe" implies, the Swift Package Manager
251251
/// can't safely determine if the build flags have any negative
@@ -273,7 +273,7 @@ public struct LinkerSetting: Encodable {
273273
self.data = BuildSettingData(name: name, value: value, condition: condition)
274274
}
275275

276-
/// Declare linkage to a system library.
276+
/// Declares linkage to a system library.
277277
///
278278
/// This setting is most useful when the library can't be linked
279279
/// automatically, such as C++ based libraries and non-modular
@@ -288,7 +288,7 @@ public struct LinkerSetting: Encodable {
288288
return LinkerSetting(name: "linkedLibrary", value: [library], condition: condition)
289289
}
290290

291-
/// Declare linkage to a system framework.
291+
/// Declares linkage to a system framework.
292292
///
293293
/// This setting is most useful when the framework can't be linked
294294
/// automatically, such as C++ based frameworks and non-modular
@@ -303,7 +303,7 @@ public struct LinkerSetting: Encodable {
303303
return LinkerSetting(name: "linkedFramework", value: [framework], condition: condition)
304304
}
305305

306-
/// Set unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
306+
/// Sets unsafe flags to pass arbitrary command-line flags to the corresponding build tool.
307307
///
308308
/// As the usage of the word "unsafe" implies, the Swift Package Manager
309309
/// can't safely determine if the build flags have any negative

Sources/PackageDescription/PackageDependency.swift

Lines changed: 24 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

1111
extension Package.Dependency {
1212

13-
/// Create a package dependency that uses the version requirement, starting with the given minimum version,
13+
/// Adds a package dependency that uses the version requirement, starting with the given minimum version,
1414
/// going up to the next major version.
1515
///
1616
/// This is the recommended way to specify a remote package dependency.
@@ -20,7 +20,7 @@ extension Package.Dependency {
2020
/// while making sure you don't update to a version with breaking changes,
2121
/// and helps to prevent conflicts in your dependency graph.
2222
///
23-
/// The following example allows the Swift package manager to select a version
23+
/// The following example allows the Swift Package Manager to select a version
2424
/// like a `1.2.3`, `1.2.4`, or `1.3.0`, but not `2.0.0`.
2525
///
2626
/// .package(url: "https://example.com/example-package.git", from: "1.2.3"),
@@ -37,7 +37,7 @@ extension Package.Dependency {
3737
return .init(name: nil, url: url, requirement: .upToNextMajor(from: version))
3838
}
3939

40-
/// Create a package dependency that uses the version requirement, starting with the given minimum version,
40+
/// Adds a package dependency that uses the version requirement, starting with the given minimum version,
4141
/// going up to the next major version.
4242
///
4343
/// This is the recommended way to specify a remote package dependency.
@@ -47,7 +47,7 @@ extension Package.Dependency {
4747
/// while making sure you don't update to a version with breaking changes,
4848
/// and helps to prevent conflicts in your dependency graph.
4949
///
50-
/// The following example allows the Swift package manager to select a version
50+
/// The following example allows the Swift Package Manager to select a version
5151
/// like a `1.2.3`, `1.2.4`, or `1.3.0`, but not `2.0.0`.
5252
///
5353
/// .package(url: "https://example.com/example-package.git", from: "1.2.3"),
@@ -65,7 +65,7 @@ extension Package.Dependency {
6565
return .init(name: name, url: url, requirement: .upToNextMajor(from: version))
6666
}
6767

68-
/// Add a remote package dependency given a version requirement.
68+
/// Adds a remote package dependency given a version requirement.
6969
///
7070
/// - Parameters:
7171
/// - name: The name of the package, or nil to deduce it from the URL.
@@ -80,10 +80,10 @@ extension Package.Dependency {
8080
return .init(name: nil, url: url, requirement: requirement)
8181
}
8282

83-
/// Add a remote package dependency given a version requirement.
83+
/// Adds a remote package dependency with a given version requirement.
8484
///
8585
/// - Parameters:
86-
/// - name: The name of the package, or nil to deduce it from the URL.
86+
/// - name: The name of the package, or `nil` to deduce it from the URL.
8787
/// - url: The valid Git URL of the package.
8888
/// - requirement: A dependency requirement. See static methods on `Package.Dependency.Requirement` for available options.
8989
@available(_PackageDescription, introduced: 5.2)
@@ -96,10 +96,10 @@ extension Package.Dependency {
9696
return .init(name: name, url: url, requirement: requirement)
9797
}
9898

99-
/// Add a package dependency starting with a specific minimum version, up to
99+
/// Adds a package dependency starting with a specific minimum version, up to
100100
/// but not including a specified maximum version.
101101
///
102-
/// The following example allows the Swift package manager to pick
102+
/// The following example allows the Swift Package Manager to pick
103103
/// versions `1.2.3`, `1.2.4`, `1.2.5`, but not `1.2.6`.
104104
///
105105
/// .package(url: "https://example.com/example-package.git", "1.2.3"..<"1.2.6"),
@@ -120,16 +120,16 @@ extension Package.Dependency {
120120
#endif
121121
}
122122

123-
/// Add a package dependency starting with a specific minimum version, up to
123+
/// Adds a package dependency starting with a specific minimum version, up to
124124
/// but not including a specified maximum version.
125125
///
126-
/// The following example allows the Swift package manager to pick
126+
/// The following example allows the Swift Package Manager to pick
127127
/// versions `1.2.3`, `1.2.4`, `1.2.5`, but not `1.2.6`.
128128
///
129129
/// .package(url: "https://example.com/example-package.git", "1.2.3"..<"1.2.6"),
130130
///
131131
/// - Parameters:
132-
/// - name: The name of the package, or nil to deduce it from the URL.
132+
/// - name: The name of the package, or `nil` to deduce it from the URL.
133133
/// - url: The valid Git URL of the package.
134134
/// - range: The custom version range requirement.
135135
@available(_PackageDescription, introduced: 5.2)
@@ -145,16 +145,16 @@ extension Package.Dependency {
145145
#endif
146146
}
147147

148-
/// Add a package dependency starting with a specific minimum version, going
148+
/// Adds a package dependency starting with a specific minimum version, going
149149
/// up to and including a specific maximum version.
150150
///
151-
/// The following example allows the Swift package manager to pick
151+
/// The following example allows the Swift Package Manager to pick
152152
/// versions 1.2.3, 1.2.4, 1.2.5, as well as 1.2.6.
153153
///
154154
/// .package(url: "https://example.com/example-package.git", "1.2.3"..."1.2.6"),
155155
///
156156
/// - Parameters:
157-
/// - name: The name of the package, or nil to deduce it from the URL.
157+
/// - name: The name of the package, or `nil` to deduce it from the URL.
158158
/// - url: The valid Git URL of the package.
159159
/// - range: The closed version range requirement.
160160
@available(_PackageDescription, obsoleted: 5.2)
@@ -175,16 +175,16 @@ extension Package.Dependency {
175175
#endif
176176
}
177177

178-
/// Add a package dependency starting with a specific minimum version, going
178+
/// Adds a package dependency starting with a specific minimum version, going
179179
/// up to and including a specific maximum version.
180180
///
181-
/// The following example allows the Swift package manager to pick
181+
/// The following example allows the Swift Package Manager to pick
182182
/// versions 1.2.3, 1.2.4, 1.2.5, as well as 1.2.6.
183183
///
184184
/// .package(url: "https://example.com/example-package.git", "1.2.3"..."1.2.6"),
185185
///
186186
/// - Parameters:
187-
/// - name: The name of the package, or nil to deduce it from the URL.
187+
/// - name: The name of the package, or `nil` to deduce it from the URL.
188188
/// - url: The valid Git URL of the package.
189189
/// - range: The closed version range requirement.
190190
@available(_PackageDescription, introduced: 5.2)
@@ -207,7 +207,7 @@ extension Package.Dependency {
207207
}
208208

209209
#if !PACKAGE_DESCRIPTION_4
210-
/// Add a dependency to a local package on the filesystem.
210+
/// Adds a package dependency to a local package on the filesystem.
211211
///
212212
/// The Swift Package Manager uses the package dependency as-is
213213
/// and does not perform any source control access. Local package dependencies
@@ -222,14 +222,16 @@ extension Package.Dependency {
222222
return .init(name: nil, url: path, requirement: ._localPackageItem)
223223
}
224224

225-
/// Add a dependency to a local package on the filesystem.
225+
/// Adds a package dependency to a local package on the filesystem.
226226
///
227227
/// The Swift Package Manager uses the package dependency as-is
228-
/// and does not perform any source control access. Local package dependencies
228+
/// and doesn't perform any source control access. Local package dependencies
229229
/// are especially useful during development of a new package or when working
230230
/// on multiple tightly coupled packages.
231231
///
232-
/// - Parameter path: The path of the package.
232+
/// - Parameters
233+
/// - name: The name of the Swift package or `nil` to deduce the name from path.
234+
/// - path: The local path to the package.
233235
@available(_PackageDescription, introduced: 5.2)
234236
public static func package(
235237
name: String? = nil,

0 commit comments

Comments
 (0)