diff --git a/Sources/ArgumentParser/Completions/CompletionsGenerator.swift b/Sources/ArgumentParser/Completions/CompletionsGenerator.swift index 010a2235d..f5e41f540 100644 --- a/Sources/ArgumentParser/Completions/CompletionsGenerator.swift +++ b/Sources/ArgumentParser/Completions/CompletionsGenerator.swift @@ -56,31 +56,25 @@ public struct CompletionShell: RawRepresentable, Hashable, CaseIterable { static let _requesting = Mutex(nil) - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/924 - /// While generating a shell completion script or while a Swift custom - /// completion function is executing to offer completions for a word from a - /// command line (e.g., while `customCompletion` from - /// `@Option(completion: .custom(customCompletion))` executes), an instance - /// representing the shell for which completions will be or are being - /// requested, respectively. + /// The shell for which completions will be or are being requested. /// - /// Otherwise `nil`. + /// `CompletionShell.requesting` is non-`nil` only while generating a shell + /// completion script or while a Swift custom completion function is executing + /// to offer completions for a word from a command line (that is, while + /// `customCompletion` from `@Option(completion: .custom(customCompletion))` + /// executes). public static var requesting: CompletionShell? { Self._requesting.withLock { $0 } } static let _requestingVersion = Mutex(nil) - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/924 - /// While a Swift custom completion function is executing to offer completions - /// for a word from a command line (e.g., while `customCompletion` from - /// `@Option(completion: .custom(customCompletion))` executes), a `String` - /// representing the version of the shell for which completions are being - /// requested. + /// The shell version for which completions will be or are being requested. /// - /// Otherwise `nil`. + /// `CompletionShell.requestingVersion` is non-`nil` only while generating a + /// shell completion script or while a Swift custom completion function is + /// running (that is, while `customCompletion` from + /// `@Option(completion: .custom(customCompletion))` executes). public static var requestingVersion: String? { Self._requestingVersion.withLock { $0 } } diff --git a/Sources/ArgumentParser/Parsable Properties/Errors.swift b/Sources/ArgumentParser/Parsable Properties/Errors.swift index 87313916a..a779809d3 100644 --- a/Sources/ArgumentParser/Parsable Properties/Errors.swift +++ b/Sources/ArgumentParser/Parsable Properties/Errors.swift @@ -62,9 +62,7 @@ public struct ExitCode: Error, RawRepresentable, Hashable { } } -// swift-format-ignore: BeginDocumentationCommentWithOneLineSummary -// https://github.com/swiftlang/swift-format/issues/924 -/// An error type that represents a clean (i.e. non-error state) exit of the +/// An error type that represents a clean (non-error state) exit of the /// utility. /// /// Throwing a `CleanExit` instance from a `validate` or `run` method, or diff --git a/Sources/ArgumentParser/Parsable Properties/Flag.swift b/Sources/ArgumentParser/Parsable Properties/Flag.swift index 881b11782..90dcdb54f 100644 --- a/Sources/ArgumentParser/Parsable Properties/Flag.swift +++ b/Sources/ArgumentParser/Parsable Properties/Flag.swift @@ -152,8 +152,6 @@ public struct FlagInversion: Hashable { self.init(base: .prefixedNo) } - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/924 /// Uses matching flags with `enable-` and `disable-` prefixes. /// /// For example, the `extraOutput` property in this declaration is set to diff --git a/Sources/ArgumentParser/Parsable Types/ParsableArgumentsValidation.swift b/Sources/ArgumentParser/Parsable Types/ParsableArgumentsValidation.swift index 7b419f0ee..94605adf4 100644 --- a/Sources/ArgumentParser/Parsable Types/ParsableArgumentsValidation.swift +++ b/Sources/ArgumentParser/Parsable Types/ParsableArgumentsValidation.swift @@ -65,8 +65,8 @@ extension ArgumentSet { } } -// swift-format-ignore: BeginDocumentationCommentWithOneLineSummary -// https://github.com/swiftlang/swift-format/issues/925 +/// A validator for positional argument arrays. +/// /// For positional arguments to be valid, there must be at most one /// positional array argument, and it must be the last positional argument /// in the argument list. Any other configuration leads to ambiguity in @@ -131,7 +131,7 @@ struct PositionalArgumentsValidator: ParsableArgumentsValidator { } } -/// Ensure that all arguments have corresponding coding keys. +/// A validator that ensures that all arguments have corresponding coding keys. struct ParsableArgumentsCodingKeyValidator: ParsableArgumentsValidator { private struct Validator: Decoder { @@ -252,7 +252,8 @@ struct ParsableArgumentsCodingKeyValidator: ParsableArgumentsValidator { } } -/// Ensure argument names are unique within a `ParsableArguments` or `ParsableCommand`. +/// A validator that ensures argument names are unique within a +/// `ParsableArguments` or `ParsableCommand`. struct ParsableArgumentsUniqueNamesValidator: ParsableArgumentsValidator { struct Error: ParsableArgumentsValidatorError, CustomStringConvertible { var duplicateNames: [String: Int] = [:] @@ -295,6 +296,7 @@ struct ParsableArgumentsUniqueNamesValidator: ParsableArgumentsValidator { } } +/// A validator that prevents declaring flags that can't be turned off. struct NonsenseFlagsValidator: ParsableArgumentsValidator { struct Error: ParsableArgumentsValidatorError, CustomStringConvertible { var names: [String] diff --git a/Sources/ArgumentParser/Usage/HelpGenerator.swift b/Sources/ArgumentParser/Usage/HelpGenerator.swift index 5250d1ddf..d4bfe21ee 100644 --- a/Sources/ArgumentParser/Usage/HelpGenerator.swift +++ b/Sources/ArgumentParser/Usage/HelpGenerator.swift @@ -416,9 +416,7 @@ extension CommandConfiguration { } extension NameSpecification { - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/924 - /// Generates a list of `Name`s for the help command at any visibility level. + /// Generates a list of names for the help command at any visibility level. /// /// If the `default` visibility is used, the help names are returned /// unmodified. If a non-default visibility is used the short names are @@ -445,13 +443,11 @@ extension NameSpecification { } extension BidirectionalCollection where Element == ParsableCommand.Type { - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/924 - /// Returns a list of help names at the request visibility level for the top- - /// most ParsableCommand in the command stack with custom helpNames + /// Returns a list of help names at the requested visibility level for the + /// top-most command in the command stack with custom help names. /// - /// If the command stack contains no custom help names the default help - /// names. + /// If the command stack contains no custom help names, returns the default + /// help names. func getHelpNames(visibility: ArgumentVisibility) -> [Name] { self.lazy.reversed().compactMap { $0.configuration.helpNames } .first diff --git a/Tests/ArgumentParserEndToEndTests/DefaultsEndToEndTests.swift b/Tests/ArgumentParserEndToEndTests/DefaultsEndToEndTests.swift index f41c07800..fadcab147 100644 --- a/Tests/ArgumentParserEndToEndTests/DefaultsEndToEndTests.swift +++ b/Tests/ArgumentParserEndToEndTests/DefaultsEndToEndTests.swift @@ -451,10 +451,12 @@ extension DefaultsEndToEndTests { } } - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/925 - /// Tests that *not* providing a default value still parses the argument correctly from the command-line. - /// This test is almost certainly duplicated by others in the repository, but allows for quick use of test filtering during development on the initialization functionality. + /// Tests that *not* providing a default value still parses the argument + /// correctly from the command-line. + /// + /// This test is almost certainly duplicated by others in the repository, + /// but allows for quick use of test filtering during development on the + /// initialization functionality. func testParsing_OptionPropertyInit_NoDefault_NoTransform() throws { AssertParse( OptionPropertyInitArguments_NoDefault_NoTransform.self, @@ -464,18 +466,18 @@ extension DefaultsEndToEndTests { } } - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/925 - /// Tests that using default property initialization syntax on a property with a `transform` function provided parses the default value for the argument when nothing is provided from the command-line. + /// Tests that using default property initialization syntax on a property + /// with a transform function provided parses the default value for the + /// argument when nothing is provided from the command-line. func testParsing_OptionPropertyInit_Default_Transform_UseDefault() throws { AssertParse(OptionPropertyInitArguments_Default.self, []) { arguments in XCTAssertEqual(arguments.transformedData, "test") } } - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/925 - /// Tests that using default property initialization syntax on a property with a `transform` function provided parses and transforms the command-line-provided value for the argument when provided. + /// Tests that using default property initialization syntax on a property + /// with a transform function provided parses and transforms the + /// command-line-provided value for the argument when provided. func testParsing_OptionPropertyInit_Default_Transform_OverrideDefault() throws { AssertParse( @@ -485,10 +487,13 @@ extension DefaultsEndToEndTests { } } - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/925 - /// Tests that *not* providing a default value for a property with a `transform` function still parses the argument correctly from the command-line. - /// This test is almost certainly duplicated by others in the repository, but allows for quick use of test filtering during development on the initialization functionality. + /// Tests that *not* providing a default value for a property with a + /// transform function still parses the argument correctly from the + /// command-line. + /// + /// This test is almost certainly duplicated by others in the repository, + /// but allows for quick use of test filtering during development on the + /// initialization functionality. func testParsing_OptionPropertyInit_NoDefault_Transform() throws { AssertParse( OptionPropertyInitArguments_NoDefault_Transform.self, @@ -550,10 +555,12 @@ extension DefaultsEndToEndTests { } } - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/925 - /// Tests that *not* providing a default value still parses the argument correctly from the command-line. - /// This test is almost certainly duplicated by others in the repository, but allows for quick use of test filtering during development on the initialization functionality. + /// Tests that *not* providing a default value still parses the argument + /// correctly from the command-line. + /// + /// This test is almost certainly duplicated by others in the repository, but + /// allows for quick use of test filtering during development on the + /// initialization functionality. func testParsing_ArgumentPropertyInit_NoDefault_NoTransform() throws { AssertParse( ArgumentPropertyInitArguments_NoDefault_NoTransform.self, ["test"] @@ -582,10 +589,13 @@ extension DefaultsEndToEndTests { } } - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/925 - /// Tests that *not* providing a default value for a property with a `transform` function still parses the argument correctly from the command-line. - /// This test is almost certainly duplicated by others in the repository, but allows for quick use of test filtering during development on the initialization functionality. + /// Tests that *not* providing a default value for a property with a + /// transform function still parses the argument correctly from the + /// command-line. + /// + /// This test is almost certainly duplicated by others in the repository, + /// but allows for quick use of test filtering during development on the + /// initialization functionality. func testParsing_ArgumentPropertyInit_NoDefault_Transform() throws { AssertParse( ArgumentPropertyInitArguments_NoDefault_Transform.self, ["test"] @@ -654,10 +664,12 @@ extension DefaultsEndToEndTests { } } - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/925 - /// Tests that *not* providing a default value still parses the argument correctly from the command-line. - /// This test is almost certainly duplicated by others in the repository, but allows for quick use of test filtering during development on the initialization functionality. + /// Tests that *not* providing a default value still parses the argument + /// correctly from the command-line. + /// + /// This test is almost certainly duplicated by others in the repository, but + /// allows for quick use of test filtering during development on the + /// initialization functionality. func testParsing_FlagPropertyInit_Bool_NoDefault() throws { AssertParse(FlagPropertyInitArguments_Bool_NoDefault.self, ["--data"]) { arguments in @@ -707,10 +719,12 @@ extension DefaultsEndToEndTests { } } - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/925 - /// Tests that *not* providing a default value still parses the argument correctly from the command-line. - /// This test is almost certainly duplicated by others in the repository, but allows for quick use of test filtering during development on the initialization functionality. + /// Tests that *not* providing a default value still parses the argument + /// correctly from the command-line. + /// + /// This test is almost certainly duplicated by others in the repository, but + /// allows for quick use of test filtering during development on the + /// initialization functionality. func testParsing_FlagPropertyInit_EnumerableFlag_NoDefault() throws { AssertParse( FlagPropertyInitArguments_EnumerableFlag_NoDefault.self, ["--data"] @@ -916,8 +930,6 @@ extension DefaultsEndToEndTests { // MARK: Overload selection -// swift-format-ignore: AlwaysUseLowerCamelCase -// https://github.com/apple/swift-argument-parser/issues/710 extension DefaultsEndToEndTests { private struct AbsolutePath: ExpressibleByArgument { init(_ value: String) {} @@ -938,11 +950,11 @@ extension DefaultsEndToEndTests { var path4 = AbsolutePath("abc") } - // swift-format-ignore: BeginDocumentationCommentWithOneLineSummary - // https://github.com/swiftlang/swift-format/issues/925 /// Tests that a non-optional `Value` type is inferred, regardless of how the - /// initializer parameters are spelled. Previously, string literals and - /// `.init` calls for the help parameter inferred different generic types. + /// initializer parameters are spelled. + /// + /// Previously, string literals and `.init` calls for the help parameter + /// inferred different generic types. func testHelpInitInferredType() throws { AssertParse(TwoPaths.self, []) { cmd in XCTAssert(type(of: cmd.path1) == AbsolutePath.self) diff --git a/Tests/ArgumentParserEndToEndTests/SourceCompatEndToEndTests.swift b/Tests/ArgumentParserEndToEndTests/SourceCompatEndToEndTests.swift index 5722c16c6..2918bd648 100644 --- a/Tests/ArgumentParserEndToEndTests/SourceCompatEndToEndTests.swift +++ b/Tests/ArgumentParserEndToEndTests/SourceCompatEndToEndTests.swift @@ -13,10 +13,8 @@ import ArgumentParser import ArgumentParserTestHelpers import XCTest -// swift-format-ignore: BeginDocumentationCommentWithOneLineSummary -// https://github.com/swiftlang/swift-format/issues/925 -/// The goal of this test class is to validate source compatibility. By running -/// this class's tests, all property wrapper initializers should be called. +// The goal of this test class is to validate source compatibility. By running +// this class's tests, all property wrapper initializers should be called. final class SourceCompatEndToEndTests: XCTestCase {} // MARK: - Property Wrapper Initializers