Skip to content

normalize abstracts and help content for swift commands #8566

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

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

normalize abstracts and help content for swift commands #8566

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d620207
Normalize help and abstracts for commands
heckj Apr 28, 2025
0cb877e
Update Sources/Commands/SwiftTestCommand.swift
heckj Apr 29, 2025
85f5d1e
fixes one test
heckj Apr 29, 2025
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
4 changes: 2 additions & 2 deletions Sources/Commands/PackageCommands/APIDiff.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ struct DeprecatedAPIDiff: ParsableCommand {
struct APIDiff: AsyncSwiftCommand {
static let configuration = CommandConfiguration(
commandName: "diagnose-api-breaking-changes",
abstract: "Diagnose API-breaking changes to Swift modules in a package",
abstract: "Diagnose API-breaking changes to Swift modules in a package.",
discussion: """
The diagnose-api-breaking-changes command can be used to compare the Swift API of \
a package to a baseline revision, diagnosing any breaking changes which have \
Expand All @@ -59,7 +59,7 @@ struct APIDiff: AsyncSwiftCommand {
""")
var breakageAllowlistPath: AbsolutePath?

@Argument(help: "The baseline treeish to compare to (e.g. a commit hash, branch name, tag, etc.)")
@Argument(help: "The baseline treeish to compare to (for example, a commit hash, branch name, tag, and so on).")
var treeish: String

@Option(parsing: .upToNextOption,
Expand Down
18 changes: 9 additions & 9 deletions Sources/Commands/PackageCommands/AddDependency.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,34 +26,34 @@ import Workspace
extension SwiftPackageCommand {
struct AddDependency: SwiftCommand {
package static let configuration = CommandConfiguration(
abstract: "Add a package dependency to the manifest"
abstract: "Add a package dependency to the manifest."
)

@Argument(help: "The URL or directory of the package to add")
@Argument(help: "The URL or directory of the package to add.")
var dependency: String

@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions

@Option(help: "The exact package version to depend on")
@Option(help: "The exact package version to depend on.")
var exact: Version?

@Option(help: "The specific package revision to depend on")
@Option(help: "The specific package revision to depend on.")
var revision: String?

@Option(help: "The branch of the package to depend on")
@Option(help: "The branch of the package to depend on.")
var branch: String?

@Option(help: "The package version to depend on (up to the next major version)")
@Option(help: "The package version to depend on (up to the next major version).")
var from: Version?

@Option(help: "The package version to depend on (up to the next minor version)")
@Option(help: "The package version to depend on (up to the next minor version).")
var upToNextMinorFrom: Version?

@Option(help: "Specify upper bound on the package version range (exclusive)")
@Option(help: "Specify upper bound on the package version range (exclusive).")
var to: Version?

@Option(help: "Specify dependency type")
@Option(help: "Specify dependency type.")
var type: DependencyType = .url

enum DependencyType: String, Codable, CaseIterable, ExpressibleByArgument {
Expand Down
8 changes: 4 additions & 4 deletions Sources/Commands/PackageCommands/AddProduct.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,20 +36,20 @@ extension SwiftPackageCommand {
}

package static let configuration = CommandConfiguration(
abstract: "Add a new product to the manifest")
abstract: "Add a new product to the manifest.")

@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions

@Argument(help: "The name of the new product")
@Argument(help: "The name of the new product.")
var name: String

@Option(help: "The type of target to add")
@Option(help: "The type of target to add.")
var type: CommandProductType = .library

@Option(
parsing: .upToNextOption,
help: "A list of targets that are part of this product"
help: "A list of targets that are part of this product."
)
var targets: [String] = []

Expand Down
6 changes: 3 additions & 3 deletions Sources/Commands/PackageCommands/AddSetting.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,19 +33,19 @@ extension SwiftPackageCommand {
}

package static let configuration = CommandConfiguration(
abstract: "Add a new setting to the manifest"
abstract: "Add a new setting to the manifest."
)

@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions

@Option(help: "The target to add the setting to")
@Option(help: "The target to add the setting to.")
var target: String

@Option(
name: .customLong("swift"),
parsing: .unconditionalSingleValue,
help: "The Swift language setting(s) to add. Supported settings: \(SwiftSetting.allCases.map(\.rawValue).joined(separator: ", "))"
help: "The Swift language setting(s) to add. Supported settings: \(SwiftSetting.allCases.map(\.rawValue).joined(separator: ", "))."
)
var _swiftSettings: [String]

Expand Down
16 changes: 8 additions & 8 deletions Sources/Commands/PackageCommands/AddTarget.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,33 +36,33 @@ extension SwiftPackageCommand {
}

package static let configuration = CommandConfiguration(
abstract: "Add a new target to the manifest")
abstract: "Add a new target to the manifest.")

@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions

@Argument(help: "The name of the new target")
@Argument(help: "The name of the new target.")
var name: String

@Option(help: "The type of target to add")
@Option(help: "The type of target to add.")
var type: TargetType = .library

@Option(
parsing: .upToNextOption,
help: "A list of target dependency names"
help: "A list of target dependency names."
)
var dependencies: [String] = []

@Option(help: "The URL for a remote binary target")
@Option(help: "The URL for a remote binary target.")
var url: String?

@Option(help: "The path to a local binary target")
@Option(help: "The path to a local binary target.")
var path: String?

@Option(help: "The checksum for a remote binary target")
@Option(help: "The checksum for a remote binary target.")
var checksum: String?

@Option(help: "The testing library to use when generating test targets, which can be one of 'xctest', 'swift-testing', or 'none'")
@Option(help: "The testing library to use when generating test targets, which can be one of 'xctest', 'swift-testing', or 'none'.")
var testingLibrary: PackageModelSyntax.AddTarget.TestHarness = .default

func run(_ swiftCommandState: SwiftCommandState) throws {
Expand Down
8 changes: 4 additions & 4 deletions Sources/Commands/PackageCommands/AddTargetDependency.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,18 +26,18 @@ import Workspace
extension SwiftPackageCommand {
struct AddTargetDependency: SwiftCommand {
package static let configuration = CommandConfiguration(
abstract: "Add a new target dependency to the manifest")
abstract: "Add a new target dependency to the manifest.")

@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions

@Argument(help: "The name of the new dependency")
@Argument(help: "The name of the new dependency.")
var dependencyName: String

@Argument(help: "The name of the target to update")
@Argument(help: "The name of the target to update.")
var targetName: String

@Option(help: "The package in which the dependency resides")
@Option(help: "The package in which the dependency resides.")
var package: String?

func run(_ swiftCommandState: SwiftCommandState) throws {
Expand Down
4 changes: 2 additions & 2 deletions Sources/Commands/PackageCommands/ArchiveSource.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,15 @@ extension SwiftPackageCommand {
struct ArchiveSource: AsyncSwiftCommand {
static let configuration = CommandConfiguration(
commandName: "archive-source",
abstract: "Create a source archive for the package"
abstract: "Create a source archive for the package."
)

@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions

@Option(
name: [.short, .long],
help: "The absolute or relative path for the generated source archive"
help: "The absolute or relative path for the generated source archive."
)
var output: AbsolutePath?

Expand Down
4 changes: 2 additions & 2 deletions Sources/Commands/PackageCommands/CompletionCommand.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ extension SwiftPackageCommand {
struct CompletionCommand: AsyncSwiftCommand {
static let configuration = CommandConfiguration(
commandName: "completion-tool",
abstract: "Completion command (for shell completions)"
abstract: "Command to generate shell completions."
)

enum Mode: String, CaseIterable, ExpressibleByArgument {
Expand Down Expand Up @@ -52,7 +52,7 @@ extension SwiftPackageCommand {
@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions

@Argument(help: "Type of completions to list")
@Argument(help: "Type of completions to list.")
var mode: Mode

func run(_ swiftCommandState: SwiftCommandState) async throws {
Expand Down
2 changes: 1 addition & 1 deletion Sources/Commands/PackageCommands/ComputeChecksum.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ struct ComputeChecksum: SwiftCommand {
@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions

@Argument(help: "The absolute or relative path to the binary artifact")
@Argument(help: "The absolute or relative path to the binary artifact.")
var path: AbsolutePath

func run(_ swiftCommandState: SwiftCommandState) throws {
Expand Down
16 changes: 8 additions & 8 deletions Sources/Commands/PackageCommands/Config.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ extension SwiftPackageCommand {
extension SwiftPackageCommand.Config {
struct SetMirror: SwiftCommand {
static let configuration = CommandConfiguration(
abstract: "Set a mirror for a dependency"
abstract: "Set a mirror for a dependency."
)

@OptionGroup(visibility: .hidden)
Expand All @@ -45,10 +45,10 @@ extension SwiftPackageCommand.Config {
@Option(name: .customLong("mirror-url"), help: .hidden)
var _deprecate_mirrorURL: String?

@Option(help: "The original url or identity")
@Option(help: "The original url or identity.")
var original: String?

@Option(help: "The mirror url or identity")
@Option(help: "The mirror url or identity.")
var mirror: String?

func run(_ swiftCommandState: SwiftCommandState) throws {
Expand Down Expand Up @@ -88,7 +88,7 @@ extension SwiftPackageCommand.Config {

struct UnsetMirror: SwiftCommand {
static let configuration = CommandConfiguration(
abstract: "Remove an existing mirror"
abstract: "Remove an existing mirror."
)

@OptionGroup(visibility: .hidden)
Expand All @@ -103,10 +103,10 @@ extension SwiftPackageCommand.Config {
@Option(name: .customLong("mirror-url"), help: .hidden)
var _deprecate_mirrorURL: String?

@Option(help: "The original url or identity")
@Option(help: "The original url or identity.")
var original: String?

@Option(help: "The mirror url or identity")
@Option(help: "The mirror url or identity.")
var mirror: String?

func run(_ swiftCommandState: SwiftCommandState) throws {
Expand Down Expand Up @@ -143,7 +143,7 @@ extension SwiftPackageCommand.Config {

struct GetMirror: SwiftCommand {
static let configuration = CommandConfiguration(
abstract: "Print mirror configuration for the given package dependency"
abstract: "Print mirror configuration for the given package dependency."
)

@OptionGroup(visibility: .hidden)
Expand All @@ -154,7 +154,7 @@ extension SwiftPackageCommand.Config {
@Option(name: .customLong("original-url"), help: .hidden)
var _deprecate_originalURL: String?

@Option(help: "The original url or identity")
@Option(help: "The original url or identity.")
var original: String?

func run(_ swiftCommandState: SwiftCommandState) throws {
Expand Down
6 changes: 3 additions & 3 deletions Sources/Commands/PackageCommands/Describe.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,12 @@ import struct TSCBasic.StringError
extension SwiftPackageCommand {
struct Describe: AsyncSwiftCommand {
static let configuration = CommandConfiguration(
abstract: "Describe the current package")
abstract: "Describe the current package.")

@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions

@Option(help: "Set the output format")
@Option(help: "Set the output format.")
var type: DescribeMode = .text

func run(_ swiftCommandState: SwiftCommandState) async throws {
Expand Down
4 changes: 2 additions & 2 deletions Sources/Commands/PackageCommands/DumpCommands.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ import XCBuildSupport

struct DumpSymbolGraph: AsyncSwiftCommand {
static let configuration = CommandConfiguration(
abstract: "Dump Symbol Graph")
abstract: "Dump symbol graphs.")
static let defaultMinimumAccessLevel = SymbolGraphExtract.AccessLevel.public

@OptionGroup(visibility: .hidden)
Expand All @@ -35,7 +35,7 @@ struct DumpSymbolGraph: AsyncSwiftCommand {
@Flag(help: "Skip members inherited through classes or default implementations.")
var skipSynthesizedMembers = false

@Option(help: "Include symbols with this access level or more. Possible values: \(SymbolGraphExtract.AccessLevel.allValueStrings.joined(separator: " | "))")
@Option(help: "Include symbols with this access level or more. Possible values: \(SymbolGraphExtract.AccessLevel.allValueStrings.joined(separator: " | ")).")
var minimumAccessLevel = defaultMinimumAccessLevel

@Flag(help: "Skip emitting doc comments for members inherited through classes or default implementations.")
Expand Down
16 changes: 8 additions & 8 deletions Sources/Commands/PackageCommands/EditCommands.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,21 +19,21 @@ import Workspace
extension SwiftPackageCommand {
struct Edit: AsyncSwiftCommand {
static let configuration = CommandConfiguration(
abstract: "Put a package in editable mode")
abstract: "Put a package in editable mode.")

@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions

@Option(help: "The revision to edit", transform: { Revision(identifier: $0) })
@Option(help: "The revision to edit.", transform: { Revision(identifier: $0) })
var revision: Revision?

@Option(name: .customLong("branch"), help: "The branch to create")
@Option(name: .customLong("branch"), help: "The branch to create.")
var checkoutBranch: String?

@Option(help: "Create or use the checkout at this path")
@Option(help: "Create or use the checkout at this path.")
var path: AbsolutePath?

@Argument(help: "The identity of the package to edit")
@Argument(help: "The identity of the package to edit.")
var packageIdentity: String

func run(_ swiftCommandState: SwiftCommandState) async throws {
Expand All @@ -53,16 +53,16 @@ extension SwiftPackageCommand {

struct Unedit: AsyncSwiftCommand {
static let configuration = CommandConfiguration(
abstract: "Remove a package from editable mode")
abstract: "Remove a package from editable mode.")

@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions

@Flag(name: .customLong("force"),
help: "Unedit the package even if it has uncommitted and unpushed changes")
help: "Unedit the package even if it has uncommitted and unpushed changes.")
var shouldForceRemove: Bool = false

@Argument(help: "The identity of the package to unedit")
@Argument(help: "The identity of the package to unedit.")
var packageIdentity: String

func run(_ swiftCommandState: SwiftCommandState) async throws {
Expand Down
2 changes: 1 addition & 1 deletion Sources/Commands/PackageCommands/Format.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ extension SwiftPackageCommand {
var globalOptions: GlobalOptions

@Argument(parsing: .captureForPassthrough,
help: "Pass flag through to the swift-format tool")
help: "Pass flag through to the swift-format tool.")
var swiftFormatFlags: [String] = []

func run(_ swiftCommandState: SwiftCommandState) async throws {
Expand Down
4 changes: 2 additions & 2 deletions Sources/Commands/PackageCommands/Init.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ import SPMBuildCore
extension SwiftPackageCommand {
struct Init: SwiftCommand {
public static let configuration = CommandConfiguration(
abstract: "Initialize a new package")
abstract: "Initialize a new package.")

@OptionGroup(visibility: .hidden)
var globalOptions: GlobalOptions
Expand All @@ -47,7 +47,7 @@ extension SwiftPackageCommand {
@OptionGroup()
var testLibraryOptions: TestLibraryOptions

@Option(name: .customLong("name"), help: "Provide custom package name")
@Option(name: .customLong("name"), help: "Provide custom package name.")
var packageName: String?

// This command should support creating the supplied --package-path if it isn't created.
Expand Down
2 changes: 1 addition & 1 deletion Sources/Commands/PackageCommands/Install.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ extension SwiftPackageCommand {
@OptionGroup()
var globalOptions: GlobalOptions

@Option(help: "The name of the executable product to install")
@Option(help: "The name of the executable product to install.")
var product: String?

func run(_ commandState: SwiftCommandState) async throws {
Expand Down
Loading