Fix several one-line summary doc comment issues (#743)

Author: natecook1000

Sources/ArgumentParser/Completions/CompletionsGenerator.swift

@@ -56,31 +56,25 @@ public struct CompletionShell: RawRepresentable, Hashable, CaseIterable {
 
   static let _requesting = Mutex<CompletionShell?>(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<String?>(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 }
   }

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

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

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]

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

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)

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