Update documentation

Sources/ArgumentParser/Documentation.docc/ArgumentParser.md

@@ -49,8 +49,8 @@ and then either calls your `run()` method or exits with a useful message.
 ### Essentials
 
 - <doc:GettingStarted>
-- <doc:CommandsAndSubcommands>
 - ``ParsableCommand``
+- ``AsyncParsableCommand``
 
 ### Arguments, Options, and Flags
 
@@ -65,6 +65,7 @@ and then either calls your `run()` method or exits with a useful message.
 
 - <doc:CustomizingHelp>
 - ``ArgumentHelp``
+- ``ArgumentVisibility``
 - ``NameSpecification``
 
 ### Custom Types

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

@@ -35,7 +35,7 @@ SUBCOMMANDS:
   See 'math help stats <subcommand>' for detailed help.
 ```
 
-Start by defining the root `Math` command. You can provide a static `configuration` property for a command that specifies its subcommands and a default subcommand, if any.
+Start by defining the root `Math` command. You can provide a static ``ParsableCommand/configuration-35km1`` property for a command that specifies its subcommands and a default subcommand, if any.
 
 ```swift
 struct Math: ParsableCommand {
@@ -53,7 +53,7 @@ struct Math: ParsableCommand {
 32
 ```
 
-Next, define a `ParsableArguments` type with properties that will be shared across multiple subcommands. Types that conform to `ParsableArguments` can be parsed from command-line arguments, but don't provide any execution through a `run()` method.
+Next, define a ``ParsableArguments`` type with properties that will be shared across multiple subcommands. Types that conform to `ParsableArguments` can be parsed from command-line arguments, but don't provide any execution through a `run()` method.
 
 In this case, the `Options` type accepts a `--hexadecimal-output` flag and expects a list of integers.
 
@@ -67,7 +67,7 @@ struct Options: ParsableArguments {
 }
 ```
 
-It's time to define our first two subcommands: `Add` and `Multiply`. Both of these subcommands include the arguments defined in the `Options` type by denoting that property with the `@OptionGroup` property wrapper. `@OptionGroup` doesn't define any new arguments for a command; instead, it splats in the arguments defined by another `ParsableArguments` type.
+It's time to define our first two subcommands: `Add` and `Multiply`. Both of these subcommands include the arguments defined in the `Options` type by denoting that property with the `@OptionGroup` property wrapper (see ``OptionGroup``). `@OptionGroup` doesn't define any new arguments for a command; instead, it splats in the arguments defined by another `ParsableArguments` type.
 
 ```swift
 extension Math {
@@ -173,10 +173,13 @@ extension Math.Statistics {
 }
 ```
 
-Last but not least, we kick off parsing and execution with a call to the static `main` method on the type at the root of our command tree. The call to main parses the command-line arguments, determines whether a subcommand was selected, and then instantiates and calls the `run()` method on that particular subcommand.
+Last but not least, we add the `@main` attribute to the root of our command tree, to tell the compiler to use that as the program's entry point. Upon execution, this parses the command-line arguments, determines whether a subcommand was selected, and then instantiates and calls the `run()` method on that particular subcommand.
 
 ```swift
-Math.main()
+@main
+struct Math: ParsableCommand {
+    // ...
+}
 ```
 
-That's it for this doubly-nested `math` command! This example is also provided as a part of the `swift-argument-parser` repository, so you can see it all together and experiment with it [here](https://github.com/apple/swift-argument-parser/blob/main/Examples/math/main.swift).
+That's it for this doubly-nested `math` command! This example is also provided as a part of the `swift-argument-parser` repository, so you can see it all together and experiment with it [here](https://github.com/apple/swift-argument-parser/blob/main/Examples/math/Math.swift).

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

@@ -0,0 +1,142 @@
+# Customizing Help for Commands
+
+Define your command's abstract, extended discussion, or usage string, and set the flags used to invoke the help display.
+
+## Overview
+
+In addition to configuring the command name and subcommands, as described in <doc:CommandsAndSubcommands>, you can also configure a command's help text by providing an abstract, discussion, or custom usage string.
+
+```swift
+struct Repeat: ParsableCommand {
+    static var configuration = CommandConfiguration(
+        abstract: "Repeats your input phrase.",
+        usage: """
+            repeat <phrase>
+            repeat --count <count> <phrase>
+            """,
+        discussion: """
+            Prints to stdout forever, or until you halt the program.
+            """)
+
+    @Argument(help: "The phrase to repeat.")
+    var phrase: String
+
+    @Option(help: "How many times to repeat.")
+    var count: Int?
+
+    mutating func run() throws {
+        for _ in 0..<(count ?? Int.max) {
+            print(phrase) 
+        }
+    }
+}
+```
+
+The customized components now appear in the generated help screen:
+
+```
+% repeat --help
+OVERVIEW: Repeats your input phrase.
+
+Prints to stdout forever, or until you halt the program.
+
+USAGE: repeat <phrase>
+       repeat --count <count> <phrase>
+
+ARGUMENTS:
+  <phrase>                The phrase to repeat.
+
+OPTIONS:
+  -h, --help              Show help information.
+
+% repeat hello!
+hello!
+hello!
+hello!
+hello!
+hello!
+hello!
+...
+```
+
+## Modifying the Help Flag Names
+
+Users can see the help screen for a command by passing either the `-h` or the `--help` flag, by default. If you need to use one of those flags for another purpose, you can provide alternative names when configuring a root command.
+
+```swift
+struct Example: ParsableCommand {
+    static let configuration = CommandConfiguration(
+        helpNames: [.long, .customShort("?")])
+
+    @Option(name: .shortAndLong, help: "The number of history entries to show.")
+    var historyDepth: Int
+
+    mutating func run() throws {
+        printHistory(depth: historyDepth)
+    }
+}
+```
+
+When running the command, `-h` matches the short name of the `historyDepth` property, and `-?` displays the help screen.
+
+```
+% example -h 3
+nmap -v -sS -O 10.2.2.2
+sshnuke 10.2.2.2 -rootpw="Z1ON0101"
+ssh 10.2.2.2 -l root
+% example -?
+USAGE: example --history-depth <history-depth>
+
+ARGUMENTS:
+  <phrase>                The phrase to repeat.
+
+OPTIONS:
+  -h, --history-depth     The number of history entries to show.
+  -?, --help              Show help information.
+```
+
+When not overridden, custom help names are inherited by subcommands. In this example, the parent command defines `--help` and `-?` as its help names:
+
+```swift
+struct Parent: ParsableCommand {
+    static let configuration = CommandConfiguration(
+        subcommands: [Child.self],
+        helpNames: [.long, .customShort("?")])
+
+    struct Child: ParsableCommand {
+        @Option(name: .shortAndLong, help: "The host the server will run on.")
+        var host: String
+    }
+}
+```
+
+The `child` subcommand inherits the parent's help names, allowing the user to distinguish between the host argument (`-h`) and help (`-?`).
+
+```
+% parent child -h 192.0.0.0
+...
+% parent child -?
+USAGE: parent child --host <host>
+
+OPTIONS:
+  -h, --host <host>       The host the server will run on.
+  -?, --help              Show help information.
+```
+
+## Hiding Commands
+
+You may not want to show every one of your command as part of your command-line interface. To render a command invisible (but still usable), pass `shouldDisplay: false` to the ``CommandConfiguration`` initializer.
+
+## Generating Help Text Programmatically
+
+The help screen is automatically shown to users when they call your command with the help flag. You can generate the same text from within your program by calling the `helpMessage()` method.
+
+```swift
+let help = Repeat.helpMessage()
+// `help` matches the output above
+
+let fortyColumnHelp = Repeat.helpMessage(columns: 40)
+// `fortyColumnHelp` is the same help screen, but wrapped to 40 columns
+```
+
+When generating help text for a subcommand, call `helpMessage(for:)` on the `ParsableCommand` type that represents the root of the command tree and pass the subcommand type as a parameter to ensure the correct display.

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

@@ -6,7 +6,7 @@ Provide custom shell completions for your command-line tool's arguments and opti
 
 `ArgumentParser` provides default completions for any types that it can. For example, an `@Option` property that is a `CaseIterable` type will automatically have the correct values as completion suggestions.
 
-When declaring an option or argument, you can customize the completions that are offered by specifying a `CompletionKind`. With this completion kind you can specify that the value should be a file, a directory, or one of a list of strings:
+When declaring an option or argument, you can customize the completions that are offered by specifying a ``CompletionKind``. With this completion kind you can specify that the value should be a file, a directory, or one of a list of strings:
 
 ```swift
 struct Example: ParsableCommand {
@@ -30,7 +30,7 @@ struct Example: ParsableCommand {
 
 The generated completion script will suggest only file names for the `--input` option, only directory names for `--output-dir`, and only the strings `markdown` and `rst` for `--format`. The `--compression` option uses the default completions for a `CaseIterable` type, so the completion script will suggest `zip` and `gzip`.
 
-You can define the default completion kind for custom `ExpressibleByArgument` types by implementing `static var defaultCompletionKind: CompletionKind`. For example, any arguments or options with this `File` type will automatically use files for completions:
+You can define the default completion kind for custom ``ExpressibleByArgument`` types by implementing ``ExpressibleByArgument/defaultCompletionKind-866se``. For example, any arguments or options with this `File` type will automatically use files for completions:
 
 ```swift
 struct File: Hashable, ExpressibleByArgument {