Skip to content

Update In-Source Documentation #2715

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 8 commits into from
Closed

Update In-Source Documentation #2715

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0dc8e03
Update source docs for Resource and Target
ElektrojungeAtWork Apr 22, 2020
bc70b4d
Merge branch 'release/5.3' into Fork/improvement/update-source-docs
ElektrojungeAtWork Apr 28, 2020
96bc77f
Another pass at the SwiftPM in-source documentation.
ElektrojungeAtWork Apr 28, 2020
8bca706
A few more tweaks to in-source docs for SwiftPM.
ElektrojungeAtWork Apr 28, 2020
20fa8d6
Use title case when refering to SwiftPM
ElektrojungeAtWork May 1, 2020
186660e
Address feedback on source docs.
ElektrojungeAtWork May 1, 2020
9b659d0
Correct in-source comment.
ElektrojungeAtWork May 1, 2020
b0ac504
Some more edits to the in-source documentation.
ElektrojungeAtWork May 2, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions Sources/PackageDescription/BuildSettings.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
///
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
///
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
46 changes: 24 additions & 22 deletions Sources/PackageDescription/PackageDependency.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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"),
Expand All @@ -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.
Expand All @@ -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"),
Expand All @@ -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.
Expand All @@ -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)
Expand All @@ -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"),
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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
Expand All @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just curious: why prefer one over the other? 🤔

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using contractions follows the Apple style guide.

“As part of Apple’s informal voice, contractions are used and recommended throughout most documentation, interface text, and marketing copy. [...]”

/// 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,
Expand Down
Loading