Make @OptionGroup(visibility:) a public API

apple · Mar 15, 2022 · d9cf7ba · d9cf7ba
1 parent 1141ed1
commit d9cf7ba
Show file tree

Hide file tree

Showing 4 changed files with 119 additions and 37 deletions.
diff --git a/Sources/ArgumentParser/Documentation.docc/Extensions/CommandConfiguration.md b/Sources/ArgumentParser/Documentation.docc/Extensions/CommandConfiguration.md
@@ -0,0 +1,29 @@
+# ``ArgumentParser/CommandConfiguration``
+
+## Topics
+
+### Creating a Configuration
+
+- ``init(commandName:abstract:usage:discussion:version:shouldDisplay:subcommands:defaultSubcommand:helpNames:)``
+
+### Customizing the Help Screen
+
+- ``abstract``
+- ``discussion``
+- ``usage``
+- ``helpNames``
+
+### Declaring Subcommands
+
+- ``subcommands``
+- ``defaultSubcommand``
+
+### Defining Command Properties
+
+- ``commandName``
+- ``version``
+- ``shouldDisplay``
+
+### Deprecated APIs
+
+- ``init(commandName:abstract:discussion:version:shouldDisplay:subcommands:defaultSubcommand:helpNames:)``
diff --git a/Sources/ArgumentParser/Documentation.docc/Extensions/OptionGroup.md b/Sources/ArgumentParser/Documentation.docc/Extensions/OptionGroup.md
@@ -0,0 +1,21 @@
+# ``ArgumentParser/OptionGroup``
+
+## Topics
+
+### Creating an Option Group
+
+
+### Array Arguments
+
+- ``init(parsing:help:completion:)``
+- ``init(parsing:help:completion:transform:)``
+- ``init(wrappedValue:parsing:help:completion:)``
+- ``init(wrappedValue:parsing:help:completion:transform:)``
+- ``ArgumentArrayParsingStrategy``
+
+### Infrequently Used APIs
+
+- ``init()``
+- ``init(from:)``
+- ``wrappedValue``
+- ``description``
diff --git a/Sources/ArgumentParser/Parsable Properties/OptionGroup.swift b/Sources/ArgumentParser/Parsable Properties/OptionGroup.swift
@@ -61,11 +61,13 @@ public struct OptionGroup<Value: ParsableArguments>: Decodable, ParsedWrapper {
     }
   }
 
-  /// Creates a property that represents another parsable type.
-  public init() {
+  /// Creates a property that represents another parsable type, using the
+  /// specified visibility.
+  public init(visibility: ArgumentVisibility = .default) {
     self.init(_parsedValue: .init { _ in
       ArgumentSet(Value.self, visibility: .private)
     })
+    self._visibility = visibility
   }
 
   /// The value presented by this property wrapper.
@@ -97,14 +99,15 @@ extension OptionGroup: CustomStringConvertible {
 
 // Experimental use with caution
 extension OptionGroup {
-  @available(*, deprecated, message: "Use init(_visibility:) instead.")
+  @available(*, deprecated, renamed: "init(visibility:)")
   public init(_hiddenFromHelp: Bool) {
-    self.init()
-    self._visibility = .hidden
+    self.init(visibility: .hidden)
   }
-
-  public init(_visibility: ArgumentVisibility) {
-    self.init()
-    self._visibility = _visibility
+
+  /// Creates a property that represents another parsable type.
+  @available(*, deprecated, renamed: "init(visibility:)")
+  @_disfavoredOverload
+  public init() {
+    self.init(visibility: .default)
   }
 }
diff --git a/Tests/ArgumentParserUnitTests/HelpGenerationTests.swift b/Tests/ArgumentParserUnitTests/HelpGenerationTests.swift
@@ -491,17 +491,25 @@ extension HelpGenerationTests {
     
     """)
   }
-
-  struct optionsToHide: ParsableArguments {
+}
+
+extension HelpGenerationTests {
+  private struct optionsToHide: ParsableArguments {
     @Flag(help: "Verbose")
     var verbose: Bool = false
 
     @Option(help: "Custom Name")
     var customName: String?
+
+    @Option(help: .hidden)
+    var hiddenOption: String?
+
+    @Argument(help: .private)
+    var privateArg: String?
   }
 
   @available(*, deprecated)
-  struct HideOptionGroupLegacyDriver: ParsableCommand {
+  private struct HideOptionGroupLegacyDriver: ParsableCommand {
     static let configuration = CommandConfiguration(commandName: "driver", abstract: "Demo hiding option groups")
 
     @OptionGroup(_hiddenFromHelp: true)
@@ -511,51 +519,72 @@ extension HelpGenerationTests {
     var timeout: Int?
   }
 
-  struct HideOptionGroupDriver: ParsableCommand {
+  private struct HideOptionGroupDriver: ParsableCommand {
     static let configuration = CommandConfiguration(commandName: "driver", abstract: "Demo hiding option groups")
 
-    @OptionGroup(_visibility: .hidden)
+    @OptionGroup(visibility: .hidden)
     var hideMe: optionsToHide
 
     @Option(help: "Time to wait before timeout (in seconds)")
     var timeout: Int?
   }
 
-  @available(*, deprecated)
-  func testHidingOptionGroup() throws {
-    let helpMessage = """
-      OVERVIEW: Demo hiding option groups
+  private struct PrivateOptionGroupDriver: ParsableCommand {
+    static let configuration = CommandConfiguration(commandName: "driver", abstract: "Demo hiding option groups")
 
-      USAGE: driver [--timeout <timeout>]
+    @OptionGroup(visibility: .private)
+    var hideMe: optionsToHide
 
-      OPTIONS:
-        --timeout <timeout>     Time to wait before timeout (in seconds)
-        -h, --help              Show help information.
+    @Option(help: "Time to wait before timeout (in seconds)")
+    var timeout: Int?
+  }
 
-      """
-    AssertHelp(.default, for: HideOptionGroupLegacyDriver.self, equals: helpMessage)
-    AssertHelp(.default, for: HideOptionGroupDriver.self, equals: helpMessage)
+  private var helpMessage: String { """
+    OVERVIEW: Demo hiding option groups
+
+    USAGE: driver [--timeout <timeout>]
+
+    OPTIONS:
+      --timeout <timeout>     Time to wait before timeout (in seconds)
+      -h, --help              Show help information.
+
+    """
   }
 
-  @available(*, deprecated)
-  func testHelpHiddenShowsAll() throws {
-    let helpHiddenMessage = """
-        OVERVIEW: Demo hiding option groups
+  private var helpHiddenMessage: String { """
+    OVERVIEW: Demo hiding option groups
+
+    USAGE: driver [--verbose] [--custom-name <custom-name>] [--hidden-option <hidden-option>] [--timeout <timeout>]
 
-        USAGE: driver [--verbose] [--custom-name <custom-name>] [--timeout <timeout>]
+    OPTIONS:
+      --verbose               Verbose
+      --custom-name <custom-name>
+                              Custom Name
+      --hidden-option <hidden-option>
+      --timeout <timeout>     Time to wait before timeout (in seconds)
+      -h, --help              Show help information.
+
+    """
+  }
 
-        OPTIONS:
-          --verbose               Verbose
-          --custom-name <custom-name>
-                                  Custom Name
-          --timeout <timeout>     Time to wait before timeout (in seconds)
-          -h, --help              Show help information.
+  @available(*, deprecated)
+  func testHidingOptionGroup() throws {
+    AssertHelp(.default, for: HideOptionGroupLegacyDriver.self, equals: helpMessage)
+    AssertHelp(.default, for: HideOptionGroupDriver.self, equals: helpMessage)
+    AssertHelp(.default, for: PrivateOptionGroupDriver.self, equals: helpMessage)
+  }
 
-        """
+  @available(*, deprecated)
+  func testHelpHiddenShowsDefaultAndHidden() throws {
     AssertHelp(.hidden, for: HideOptionGroupLegacyDriver.self, equals: helpHiddenMessage)
     AssertHelp(.hidden, for: HideOptionGroupDriver.self, equals: helpHiddenMessage)
+
+    // Note: Private option groups are not visible at `.hidden` help level.
+    AssertHelp(.hidden, for: PrivateOptionGroupDriver.self, equals: helpMessage)
   }
+}
 
+extension HelpGenerationTests {
   struct AllValues: ParsableCommand {
     enum Manual: Int, ExpressibleByArgument {
       case foo