ArgumentHelp.Visibility levels API (#390)

Author: McNight

Sources/ArgumentParser/Documentation.docc/Articles/CustomizingHelp.md

@@ -185,7 +185,7 @@ OPTIONS:
 
 ## Hiding Arguments and Commands
 
-You may want to suppress features under development or experimental flags from the generated help screen. You can hide an argument or a subcommand by passing `shouldDisplay: false` to the property wrapper or `CommandConfiguration` initializers, respectively.
+You may want to suppress features under development or experimental flags from the generated help screen. You can hide an argument or a subcommand by passing `visibility: .hidden` to the property wrapper or `CommandConfiguration` initializers, respectively.
 
 `ArgumentHelp` includes a `.hidden` static property that makes it even simpler to hide arguments:
 

Sources/ArgumentParser/Parsable Properties/ArgumentHelp.swift

@@ -11,6 +11,18 @@
 
 /// Help information for a command-line argument.
 public struct ArgumentHelp {
+  /// Visibility level of an argument's help.
+  public enum Visibility {
+      /// Show help for this argument whenever appropriate.
+      case `default`
+
+      /// Only show help for this argument in the extended help screen.
+      case hidden
+
+      /// Never show help for this argument.
+      case `private`
+  }
+
   /// A short description of the argument.
   public var abstract: String = ""
 
@@ -24,26 +36,57 @@ public struct ArgumentHelp {
   ///   flags don't include a value.
   public var valueName: String?
 
+  /// A visibility level indicating whether this argument should be shown in
+  /// the extended help display.
+  public var visibility: Visibility = .default
+
   /// A Boolean value indicating whether this argument should be shown in
   /// the extended help display.
-  public var shouldDisplay: Bool = true
+  @available(*, deprecated, message: "Use visibility level instead.")
+  public var shouldDisplay: Bool {
+    get {
+      return visibility == .default
+    }
+    set {
+      visibility = newValue ? .default : .hidden
+    }
+  }
 
   /// Creates a new help instance.
+  @available(*, deprecated, message: "Use init(_:discussion:valueName:visibility:) instead.")
   public init(
     _ abstract: String = "",
     discussion: String = "",
     valueName: String? = nil,
-    shouldDisplay: Bool = true)
+    shouldDisplay: Bool)
   {
     self.abstract = abstract
     self.discussion = discussion
     self.valueName = valueName
     self.shouldDisplay = shouldDisplay
   }
-  
-  /// A `Help` instance that hides an argument from the extended help display.
+
+  /// Creates a new help instance.
+  public init(
+    _ abstract: String = "",
+    discussion: String = "",
+    valueName: String? = nil,
+    visibility: Visibility = .default)
+  {
+    self.abstract = abstract
+    self.discussion = discussion
+    self.valueName = valueName
+    self.visibility = visibility
+  }
+
+  /// A `Help` instance that shows an argument only in the extended help display.
   public static var hidden: ArgumentHelp {
-    ArgumentHelp(shouldDisplay: false)
+    ArgumentHelp(visibility: .hidden)
+  }
+
+  /// A `Help` instance that hides an argument from the extended help display.
+  public static var `private`: ArgumentHelp {
+    ArgumentHelp(visibility: .private)
   }
 }
 

Sources/ArgumentParser/Parsing/ArgumentDefinition.swift

@@ -79,7 +79,7 @@ struct ArgumentDefinition {
       self.abstract = help?.abstract ?? ""
       self.discussion = help?.discussion ?? ""
       self.valueName = help?.valueName ?? ""
-      self.shouldDisplay = help?.shouldDisplay ?? true
+      self.shouldDisplay = (help?.visibility ?? .default) == .default
     }
   }
 

Tests/ArgumentParserUnitTests/HelpGenerationTests.swift

@@ -547,6 +547,29 @@ extension HelpGenerationTests {
     XCTAssertEqual(AllValues.SpecializedSynthesized.allValueStrings, opts[4].help.allValues)
     XCTAssertEqual(AllValues.SpecializedSynthesized.allValueStrings, opts[5].help.allValues)
   }
+
+  struct Q: ParsableArguments {
+    @Option(help: "Your name") var name: String
+    @Option(help: "Your title") var title: String?
+
+    @Argument(help: .private) var privateName: String?
+    @Option(help: .private) var privateTitle: String?
+    @Flag(help: .private) var privateFlag: Bool = false
+    @Flag(inversion: .prefixedNo, help: .private) var privateInvertedFlag: Bool = true
+  }
+
+  func testHelpWithPrivate() {
+    // For now, hidden and private have the same behaviour
+    AssertHelp(for: Q.self, equals: """
+            USAGE: q --name <name> [--title <title>]
+
+            OPTIONS:
+              --name <name>           Your name
+              --title <title>         Your title
+              -h, --help              Show help information.
+
+            """)
+  }
 }
 
 // MARK: - Issue #278 https://github.com/apple/swift-argument-parser/issues/278